[PATCH] ioctl_tty.2: Add example how to get or set baudrate on the serial port

[PATCH] ioctl_tty.2: Add example how to get or set baudrate on the serial port

[Pali Rohár via Libc-alpha]

Signed-off-by: Pali Rohár <pali@kernel.org>
---
 man2/ioctl_tty.2 | 60 ++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 60 insertions(+)

diff --git a/man2/ioctl_tty.2 b/man2/ioctl_tty.2
index 0b0083c671a7..9d394572ae93 100644
--- a/man2/ioctl_tty.2
+++ b/man2/ioctl_tty.2
@@ -750,6 +750,66 @@ main(void)
     close(fd);
 }
 .EE
+.PP
+Get or set arbitrary baudrate on the serial port.
+.PP
+.EX
+#include <stdio.h>
+#include <stdlib.h>
+#include <sys/types.h>
+#include <fcntl.h>
+#include <unistd.h>
+#include <sys/ioctl.h>
+#include <asm/termbits.h>
+
+int
+main(int argc, char *argv[])
+{
+#if !defined(TCGETS2) || !defined(TCSETS2) || !defined(BOTHER)
+    fprintf(stderr, "TCGETS2, TCSETS2 or BOTHER is unsupported\\n");
+    return 1;
+#else
+    struct termios2 tio2;
+    int fd, rc;
+
+    if (argc != 2 && argc != 3) {
+        fprintf(stderr, "Usage: %s device [new_baudrate]\\n", argv[0]);
+        return 1;
+    }
+
+    fd = open(argv[1], O_RDWR | O_NONBLOCK | O_NOCTTY);
+    if (fd < 0) {
+        perror("open");
+        return 1;
+    }
+
+    rc = ioctl(fd, TCGETS2, &tio2);
+    if (rc) {
+        perror("TCGETS2");
+        close(fd);
+        return 1;
+    }
+
+    printf("%u\\n", tio2.c_ospeed);
+
+    if (argc == 3) {
+        tio2.c_cflag &= ~CBAUD;
+        tio2.c_cflag |= BOTHER;
+        tio2.c_ospeed = tio2.c_ispeed = atoi(argv[2]);
+
+        rc = ioctl(fd, TCSETS2, &tio2);
+        if (rc) {
+            perror("TCSETS2");
+            close(fd);
+            return 1;
+        }
+    }
+
+    close(fd);
+    return 0;
+#endif
+}
+.EE
 .SH SEE ALSO
 .BR ldattach (1),
 .BR ioctl (2),
-- 
2.20.1

Re: [PATCH] ioctl_tty.2: Add example how to get or set baudrate on the serial port

[Alejandro Colomar (man-pages) via Libc-alpha]

Hi Pali,

On 7/30/21 11:53 AM, Pali Rohár wrote:
> Signed-off-by: Pali Rohár <pali@kernel.org>

Thanks for the patch!

Please see some comments below.

Cheers,

Alex


> ---
>   man2/ioctl_tty.2 | 60 ++++++++++++++++++++++++++++++++++++++++++++++++
>   1 file changed, 60 insertions(+)
> 
> diff --git a/man2/ioctl_tty.2 b/man2/ioctl_tty.2
> index 0b0083c671a7..9d394572ae93 100644
> --- a/man2/ioctl_tty.2
> +++ b/man2/ioctl_tty.2
> @@ -750,6 +750,66 @@ main(void)
>       close(fd);
>   }
>   .EE
> +.PP
> +Get or set arbitrary baudrate on the serial port.
> +.PP
> +.EX
> +#include <stdio.h>
> +#include <stdlib.h>
> +#include <sys/types.h>
> +#include <fcntl.h>
> +#include <unistd.h>
> +#include <sys/ioctl.h>
> +#include <asm/termbits.h>

Unless there's a reason to use a specific include order (and if so, add 
a comment), please use alphabetical order.

> +
> +int
> +main(int argc, char *argv[])
> +{
> +#if !defined(TCGETS2) || !defined(TCSETS2) || !defined(BOTHER)
> +    fprintf(stderr, "TCGETS2, TCSETS2 or BOTHER is unsupported\\n");
> +    return 1;
> +#else

Do we want the program to compile if those are unsupported?

Maybe you can #error there and simplify the reader having to parse the 
preprocessor directive mentally:

#if !defined...
# error ...
#endif

I know it's non-standard, but I think it's common enough so that we can 
use it here.

> +    struct termios2 tio2;
> +    int fd, rc;
> +
> +    if (argc != 2 && argc != 3) {
> +        fprintf(stderr, "Usage: %s device [new_baudrate]\\n", argv[0]);

We use \e for printing the escape character.  Not \\
CC: Branden

See groff_man(7):
    Portability
        [...]

        Similar  caveats  apply  to escapes.  Some escape sequences
        are however required for correct typesetting  even  in  man
        pages and usually do not cause portability problems:

        [...]

        \e     Widely used in man pages to  represent  a  backslash
               output  glyph.  It works reliably as long as the .ec
               request is not used, which should  never  happen  in
               man pages, and it is slightly more portable than the
               more exact ‘\(rs’  (“reverse  solidus”)  escape  se‐
               quence.


> +        return 1;
> +    }
> +
> +    fd = open(argv[1], O_RDWR | O_NONBLOCK | O_NOCTTY);
> +    if (fd < 0) {
> +        perror("open");
> +        return 1;

exit(EXIT_FAILURE);

> +    }
> +
> +    rc = ioctl(fd, TCGETS2, &tio2);
> +    if (rc) {
> +        perror("TCGETS2");
> +        close(fd);
> +        return 1;

exit(3)

> +    }
> +
> +    printf("%u\\n", tio2.c_ospeed);

\e

> +
> +    if (argc == 3) {
> +        tio2.c_cflag &= ~CBAUD;
> +        tio2.c_cflag |= BOTHER;
> +        tio2.c_ospeed = tio2.c_ispeed = atoi(argv[2]);
> +
> +        rc = ioctl(fd, TCSETS2, &tio2);
> +        if (rc) {
> +            perror("TCSETS2");
> +            close(fd);
> +            return 1;

exit(3)

> +        }
> +    }
> +
> +    close(fd);
> +    return 0;

exit(3)

> +#endif
> +}
> +.EE
>   .SH SEE ALSO
>   .BR ldattach (1),
>   .BR ioctl (2),
> 


-- 
Alejandro Colomar
Linux man-pages comaintainer; https://www.kernel.org/doc/man-pages/
http://www.alejandro-colomar.es/

Re: [PATCH] ioctl_tty.2: Add example how to get or set baudrate on the serial port

[Pali Rohár via Libc-alpha]

Hello!

On Friday 30 July 2021 13:47:06 Alejandro Colomar (man-pages) wrote:
> Hi Pali,
> 
> On 7/30/21 11:53 AM, Pali Rohár wrote:
> > Signed-off-by: Pali Rohár <pali@kernel.org>
> 
> Thanks for the patch!
> 
> Please see some comments below.
> 
> Cheers,
> 
> Alex
> 
> 
> > ---
> >   man2/ioctl_tty.2 | 60 ++++++++++++++++++++++++++++++++++++++++++++++++
> >   1 file changed, 60 insertions(+)
> > 
> > diff --git a/man2/ioctl_tty.2 b/man2/ioctl_tty.2
> > index 0b0083c671a7..9d394572ae93 100644
> > --- a/man2/ioctl_tty.2
> > +++ b/man2/ioctl_tty.2
> > @@ -750,6 +750,66 @@ main(void)
> >       close(fd);
> >   }
> >   .EE
> > +.PP
> > +Get or set arbitrary baudrate on the serial port.
> > +.PP
> > +.EX
> > +#include <stdio.h>
> > +#include <stdlib.h>
> > +#include <sys/types.h>
> > +#include <fcntl.h>
> > +#include <unistd.h>
> > +#include <sys/ioctl.h>
> > +#include <asm/termbits.h>
> 
> Unless there's a reason to use a specific include order (and if so, add a
> comment), please use alphabetical order.

Ok. Seems that alphabetical order compiles fine too.

> > +
> > +int
> > +main(int argc, char *argv[])
> > +{
> > +#if !defined(TCGETS2) || !defined(TCSETS2) || !defined(BOTHER)
> > +    fprintf(stderr, "TCGETS2, TCSETS2 or BOTHER is unsupported\\n");
> > +    return 1;
> > +#else
> 
> Do we want the program to compile if those are unsupported?

My intention was to provide example which compiles fine on any Linux
architecture and in case of error it reports it at runtime.

On architectures where are TCGETS2/TCSETS2 ioctls unsupported, there are
still supported TCGETS/TCSETS ioctls. So proper Linux portable program
should fallback to TCGETS/TCSETS ioctls with Bnnn constants.

So for example setting baudrate to 115200 would be possible via
predefined constant B115200 in c_cflag member even when struct termios2
with c_ospeed is unsupported.

I just did not put this fallback into this example as it would be quite
loooong (as it is needed to add big switch for every Bnnn constant and
convert numeric value into Bnnn) and example show how to use
TCGETS2/TCSETS2 (not TCGETS/TCSETS).

> Maybe you can #error there and simplify the reader having to parse the
> preprocessor directive mentally:
> 
> #if !defined...
> # error ...
> #endif
> 
> I know it's non-standard, but I think it's common enough so that we can use
> it here.

#error is standard. It is already defined in C99 (section 6.10.5 Error
directive).

> > +    struct termios2 tio2;
> > +    int fd, rc;
> > +
> > +    if (argc != 2 && argc != 3) {
> > +        fprintf(stderr, "Usage: %s device [new_baudrate]\\n", argv[0]);
> 
> We use \e for printing the escape character.  Not \\

Ok!

> CC: Branden
> 
> See groff_man(7):
>    Portability
>        [...]
> 
>        Similar  caveats  apply  to escapes.  Some escape sequences
>        are however required for correct typesetting  even  in  man
>        pages and usually do not cause portability problems:
> 
>        [...]
> 
>        \e     Widely used in man pages to  represent  a  backslash
>               output  glyph.  It works reliably as long as the .ec
>               request is not used, which should  never  happen  in
>               man pages, and it is slightly more portable than the
>               more exact ‘\(rs’  (“reverse  solidus”)  escape  se‐
>               quence.
> 
> 
> > +        return 1;
> > +    }
> > +
> > +    fd = open(argv[1], O_RDWR | O_NONBLOCK | O_NOCTTY);
> > +    if (fd < 0) {
> > +        perror("open");
> > +        return 1;
> 
> exit(EXIT_FAILURE);
> 
> > +    }
> > +
> > +    rc = ioctl(fd, TCGETS2, &tio2);
> > +    if (rc) {
> > +        perror("TCGETS2");
> > +        close(fd);
> > +        return 1;
> 
> exit(3)
> 
> > +    }
> > +
> > +    printf("%u\\n", tio2.c_ospeed);
> 
> \e
> 
> > +
> > +    if (argc == 3) {
> > +        tio2.c_cflag &= ~CBAUD;
> > +        tio2.c_cflag |= BOTHER;
> > +        tio2.c_ospeed = tio2.c_ispeed = atoi(argv[2]);
> > +
> > +        rc = ioctl(fd, TCSETS2, &tio2);
> > +        if (rc) {
> > +            perror("TCSETS2");
> > +            close(fd);
> > +            return 1;
> 
> exit(3)
> 
> > +        }
> > +    }
> > +
> > +    close(fd);
> > +    return 0;
> 
> exit(3)

Interesting... Do you prefer to use exit(EXIT_SUCCESS) instead of return 0?

> > +#endif
> > +}
> > +.EE
> >   .SH SEE ALSO
> >   .BR ldattach (1),
> >   .BR ioctl (2),
> > 
> 
> 
> -- 
> Alejandro Colomar
> Linux man-pages comaintainer; https://www.kernel.org/doc/man-pages/
> http://www.alejandro-colomar.es/

Re: [PATCH] ioctl_tty.2: Add example how to get or set baudrate on the serial port

[Alejandro Colomar (man-pages) via Libc-alpha]

Hi Pali,


On 7/30/21 2:05 PM, Pali Rohár wrote:

> 
>>> +
>>> +int
>>> +main(int argc, char *argv[])
>>> +{
>>> +#if !defined(TCGETS2) || !defined(TCSETS2) || !defined(BOTHER)
>>> +    fprintf(stderr, "TCGETS2, TCSETS2 or BOTHER is unsupported\\n");
>>> +    return 1;
>>> +#else
>>
>> Do we want the program to compile if those are unsupported?
> 
> My intention was to provide example which compiles fine on any Linux
> architecture and in case of error it reports it at runtime.
> 
> On architectures where are TCGETS2/TCSETS2 ioctls unsupported, there are
> still supported TCGETS/TCSETS ioctls. So proper Linux portable program
> should fallback to TCGETS/TCSETS ioctls with Bnnn constants.
> 
> So for example setting baudrate to 115200 would be possible via
> predefined constant B115200 in c_cflag member even when struct termios2
> with c_ospeed is unsupported.
> 
> I just did not put this fallback into this example as it would be quite
> loooong (as it is needed to add big switch for every Bnnn constant and
> convert numeric value into Bnnn) and example show how to use
> TCGETS2/TCSETS2 (not TCGETS/TCSETS).

Okay, I leave it up to you what you consider best to do :)

> 
>> Maybe you can #error there and simplify the reader having to parse the
>> preprocessor directive mentally:
>>
>> #if !defined...
>> # error ...
>> #endif
>>
>> I know it's non-standard, but I think it's common enough so that we can use
>> it here.
> 
> #error is standard. It is already defined in C99 (section 6.10.5 Error
> directive).

Ahh, it is #warning that is non-standard!  Thanks.  I forgot that.

> 
>>> +    struct termios2 tio2;
>>> +    int fd, rc;
>>> +
>>> +    if (argc != 2 && argc != 3) {
>>> +        fprintf(stderr, "Usage: %s device [new_baudrate]\\n", argv[0]);
>>
>> We use \e for printing the escape character.  Not \\
> 
> Ok!
> 
>> CC: Branden
>>
>> See groff_man(7):
>>     Portability
>>         [...]
>>
>>         Similar  caveats  apply  to escapes.  Some escape sequences
>>         are however required for correct typesetting  even  in  man
>>         pages and usually do not cause portability problems:
>>
>>         [...]
>>
>>         \e     Widely used in man pages to  represent  a  backslash
>>                output  glyph.  It works reliably as long as the .ec
>>                request is not used, which should  never  happen  in
>>                man pages, and it is slightly more portable than the
>>                more exact ‘\(rs’  (“reverse  solidus”)  escape  se‐
>>                quence.
>>
>>
>>> +        return 1;
>>> +    }
>>> +
>>> +    fd = open(argv[1], O_RDWR | O_NONBLOCK | O_NOCTTY);
>>> +    if (fd < 0) {
>>> +        perror("open");
>>> +        return 1;
>>
>> exit(EXIT_FAILURE);
>>
>>> +    }
>>> +
>>> +    rc = ioctl(fd, TCGETS2, &tio2);
>>> +    if (rc) {
>>> +        perror("TCGETS2");
>>> +        close(fd);
>>> +        return 1;
>>
>> exit(3)
>>
>>> +    }
>>> +
>>> +    printf("%u\\n", tio2.c_ospeed);
>>
>> \e
>>
>>> +
>>> +    if (argc == 3) {
>>> +        tio2.c_cflag &= ~CBAUD;
>>> +        tio2.c_cflag |= BOTHER;
>>> +        tio2.c_ospeed = tio2.c_ispeed = atoi(argv[2]);
>>> +
>>> +        rc = ioctl(fd, TCSETS2, &tio2);
>>> +        if (rc) {
>>> +            perror("TCSETS2");
>>> +            close(fd);
>>> +            return 1;
>>
>> exit(3)
>>
>>> +        }
>>> +    }
>>> +
>>> +    close(fd);
>>> +    return 0;
>>
>> exit(3)
> 
> Interesting... Do you prefer to use exit(EXIT_SUCCESS) instead of return 0?

I don't care in my own code.
I typically use return 0 at the end of main.
But the historical convention in manual pages is using exit(EXIT_SUCCESS),
so let's follow that :)


Tanks,

Alex


-- 
Alejandro Colomar
Linux man-pages comaintainer; https://www.kernel.org/doc/man-pages/
http://www.alejandro-colomar.es/

[PATCH v2] ioctl_tty.2: Add example how to get or set baudrate on the serial port

[Pali Rohár via Libc-alpha]

Signed-off-by: Pali Rohár <pali@kernel.org>

---
Changes in v2:
* Use \e for backslash
* Use exit(EXIT_*) instead of return num
* Sort includes
* Add comment about possible fallback
---
 man2/ioctl_tty.2 | 61 ++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 61 insertions(+)

diff --git a/man2/ioctl_tty.2 b/man2/ioctl_tty.2
index 967b5c4c78c9..771a9a470bf0 100644
--- a/man2/ioctl_tty.2
+++ b/man2/ioctl_tty.2
@@ -748,6 +748,67 @@ main(void)
     close(fd);
 }
 .EE
+.PP
+Get or set arbitrary baudrate on the serial port.
+.PP
+.EX
+#include <asm/termbits.h>
+#include <fcntl.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <sys/ioctl.h>
+#include <sys/types.h>
+#include <unistd.h>
+
+int
+main(int argc, char *argv[])
+{
+#if !defined(TCGETS2) || !defined(TCSETS2) || !defined(BOTHER)
+    fprintf(stderr, "TCGETS2, TCSETS2 or BOTHER is unsupported\en");
+    /* Program may fallback to TCGETS/TCSETS with Bnnn constants */
+    exit(EXIT_FAILURE);
+#else
+    struct termios2 tio2;
+    int fd, rc;
+
+    if (argc != 2 && argc != 3) {
+        fprintf(stderr, "Usage: %s device [new_baudrate]\en", argv[0]);
+        exit(EXIT_FAILURE);
+    }
+
+    fd = open(argv[1], O_RDWR | O_NONBLOCK | O_NOCTTY);
+    if (fd < 0) {
+        perror("open");
+        exit(EXIT_FAILURE);
+    }
+
+    rc = ioctl(fd, TCGETS2, &tio2);
+    if (rc) {
+        perror("TCGETS2");
+        close(fd);
+        exit(EXIT_FAILURE);
+    }
+
+    printf("%u\en", tio2.c_ospeed);
+
+    if (argc == 3) {
+        tio2.c_cflag &= ~CBAUD;
+        tio2.c_cflag |= BOTHER;
+        tio2.c_ospeed = tio2.c_ispeed = atoi(argv[2]);
+
+        rc = ioctl(fd, TCSETS2, &tio2);
+        if (rc) {
+            perror("TCSETS2");
+            close(fd);
+            exit(EXIT_FAILURE);
+        }
+    }
+
+    close(fd);
+    exit(EXIT_SUCCESS);
+#endif
+}
+.EE
 .SH SEE ALSO
 .BR ldattach (1),
 .BR ioctl (2),
-- 
2.20.1

[PATCH v3] ioctl_tty.2: Add example how to get or set baudrate on the serial port

[Pali Rohár via Libc-alpha]

Signed-off-by: Pali Rohár <pali@kernel.org>

---
Changes in v3:
* Check support for custom baudrate only based on BOTHER macro
* Use TCGETS/TCSETS/termios when TCGETS2/TCSETS2/termios2 is not available

Changes in v2:
* Use \e for backslash
* Use exit(EXIT_*) instead of return num
* Sort includes
* Add comment about possible fallback
---

Hello Alejandro!

I found out that this stuff is more complicated as I originally thought.
And seems that additional documentation on this topic is needed...

For setting custom baudrate it is needed to set BOTHER flag in c_cflag
field and baudrate value itself in c_ospeed and c_ispeed fields.

So when BOTHER flag is not provided by <asm/termbits.h> then setting custom
baudrate is not possible, fields c_ospeed and c_ispeed do not exist (and
only some predefined Bnnn baudrate values are supported). This applies when
compiling application with older version of header files (prior support for
custom baudrate was introduced into header files).

First caveat: BOTHER constant is different for different architectures.
So it is not possible to provide fallback #ifndef..#define BOTHER.

And now the biggest issue: Some architectures have these c_ospeed and
c_ispeed fields in struct termios and some in struct termios2.

TCGETS/TCSETS ioctls use struct termios and TCGETS/TCSETS2 use
struct termios2.

Some architectures (e.g. amd64) provide both struct termios and struct
termios2, but c_ospeed and c_ispeed are only in struct termios2.

Some other architectures (e.g. alpha) provide both struct termios and struct
termios2 and both have c_ospeed and c_ispeed fields.

And some other architectures (e.g. powerpc) provide only struct termios
(no struct termios2) and it has c_ospeed and c_ispeed fields.

So basically to support all architectures it is needed to use
struct termios2 when TCGETS2/TCSETS2 is supported. Otherwise it is needed
to use struct termios with TCGETS/TCSETS (case for e.g. powerpc).

I updated v3 patch to handle this logic.
---
 man2/ioctl_tty.2 | 73 ++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 73 insertions(+)

diff --git a/man2/ioctl_tty.2 b/man2/ioctl_tty.2
index 3020f9984872..d83cbd17225b 100644
--- a/man2/ioctl_tty.2
+++ b/man2/ioctl_tty.2
@@ -764,6 +764,79 @@ main(void)
     close(fd);
 }
 .EE
+.PP
+Get or set arbitrary baudrate on the serial port.
+.PP
+.EX
+#include <asm/termbits.h>
+#include <fcntl.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <sys/ioctl.h>
+#include <sys/types.h>
+#include <unistd.h>
+
+int
+main(int argc, char *argv[])
+{
+#ifndef BOTHER
+    fprintf(stderr, "BOTHER is unsupported\en");
+    /* Program may fallback to TCGETS/TCSETS with Bnnn constants */
+    exit(EXIT_FAILURE);
+#else
+#ifdef TCGETS2
+    struct termios2 tio;
+#else
+    struct termios tio;
+#endif
+    int fd, rc;
+
+    if (argc != 2 && argc != 3) {
+        fprintf(stderr, "Usage: %s device [new_baudrate]\en", argv[0]);
+        exit(EXIT_FAILURE);
+    }
+
+    fd = open(argv[1], O_RDWR | O_NONBLOCK | O_NOCTTY);
+    if (fd < 0) {
+        perror("open");
+        exit(EXIT_FAILURE);
+    }
+
+#ifdef TCGETS2
+    rc = ioctl(fd, TCGETS2, &tio);
+#else
+    rc = ioctl(fd, TCGETS, &tio);
+#endif
+    if (rc) {
+        perror("TCGETS");
+        close(fd);
+        exit(EXIT_FAILURE);
+    }
+
+    printf("%u\en", tio.c_ospeed);
+
+    if (argc == 3) {
+        tio.c_cflag &= ~CBAUD;
+        tio.c_cflag |= BOTHER;
+        tio.c_ospeed = tio.c_ispeed = atoi(argv[2]);
+
+#ifdef TCSETS2
+        rc = ioctl(fd, TCSETS2, &tio);
+#else
+        rc = ioctl(fd, TCSETS, &tio);
+#endif
+        if (rc) {
+            perror("TCSETS");
+            close(fd);
+            exit(EXIT_FAILURE);
+        }
+    }
+
+    close(fd);
+    exit(EXIT_SUCCESS);
+#endif
+}
+.EE
 .SH SEE ALSO
 .BR ldattach (1),
 .BR ioctl (2),
-- 
2.20.1

Re: [PATCH v3] ioctl_tty.2: Add example how to get or set baudrate on the serial port

[Pali Rohár via Libc-alpha]

+ linux-serial
+ Greg

Greg, could I ask you for reviewing this documentation manpage patch?

On Sunday 01 August 2021 15:51:45 Pali Rohár wrote:
> Signed-off-by: Pali Rohár <pali@kernel.org>
> 
> ---
> Changes in v3:
> * Check support for custom baudrate only based on BOTHER macro
> * Use TCGETS/TCSETS/termios when TCGETS2/TCSETS2/termios2 is not available
> 
> Changes in v2:
> * Use \e for backslash
> * Use exit(EXIT_*) instead of return num
> * Sort includes
> * Add comment about possible fallback
> ---
> 
> Hello Alejandro!
> 
> I found out that this stuff is more complicated as I originally thought.
> And seems that additional documentation on this topic is needed...
> 
> For setting custom baudrate it is needed to set BOTHER flag in c_cflag
> field and baudrate value itself in c_ospeed and c_ispeed fields.
> 
> So when BOTHER flag is not provided by <asm/termbits.h> then setting custom
> baudrate is not possible, fields c_ospeed and c_ispeed do not exist (and
> only some predefined Bnnn baudrate values are supported). This applies when
> compiling application with older version of header files (prior support for
> custom baudrate was introduced into header files).
> 
> First caveat: BOTHER constant is different for different architectures.
> So it is not possible to provide fallback #ifndef..#define BOTHER.
> 
> And now the biggest issue: Some architectures have these c_ospeed and
> c_ispeed fields in struct termios and some in struct termios2.
> 
> TCGETS/TCSETS ioctls use struct termios and TCGETS/TCSETS2 use
> struct termios2.
> 
> Some architectures (e.g. amd64) provide both struct termios and struct
> termios2, but c_ospeed and c_ispeed are only in struct termios2.
> 
> Some other architectures (e.g. alpha) provide both struct termios and struct
> termios2 and both have c_ospeed and c_ispeed fields.
> 
> And some other architectures (e.g. powerpc) provide only struct termios
> (no struct termios2) and it has c_ospeed and c_ispeed fields.
> 
> So basically to support all architectures it is needed to use
> struct termios2 when TCGETS2/TCSETS2 is supported. Otherwise it is needed
> to use struct termios with TCGETS/TCSETS (case for e.g. powerpc).
> 
> I updated v3 patch to handle this logic.
> ---
>  man2/ioctl_tty.2 | 73 ++++++++++++++++++++++++++++++++++++++++++++++++
>  1 file changed, 73 insertions(+)
> 
> diff --git a/man2/ioctl_tty.2 b/man2/ioctl_tty.2
> index 3020f9984872..d83cbd17225b 100644
> --- a/man2/ioctl_tty.2
> +++ b/man2/ioctl_tty.2
> @@ -764,6 +764,79 @@ main(void)
>      close(fd);
>  }
>  .EE
> +.PP
> +Get or set arbitrary baudrate on the serial port.
> +.PP
> +.EX
> +#include <asm/termbits.h>
> +#include <fcntl.h>
> +#include <stdio.h>
> +#include <stdlib.h>
> +#include <sys/ioctl.h>
> +#include <sys/types.h>
> +#include <unistd.h>
> +
> +int
> +main(int argc, char *argv[])
> +{
> +#ifndef BOTHER
> +    fprintf(stderr, "BOTHER is unsupported\en");
> +    /* Program may fallback to TCGETS/TCSETS with Bnnn constants */
> +    exit(EXIT_FAILURE);
> +#else
> +#ifdef TCGETS2
> +    struct termios2 tio;
> +#else
> +    struct termios tio;
> +#endif
> +    int fd, rc;
> +
> +    if (argc != 2 && argc != 3) {
> +        fprintf(stderr, "Usage: %s device [new_baudrate]\en", argv[0]);
> +        exit(EXIT_FAILURE);
> +    }
> +
> +    fd = open(argv[1], O_RDWR | O_NONBLOCK | O_NOCTTY);
> +    if (fd < 0) {
> +        perror("open");
> +        exit(EXIT_FAILURE);
> +    }
> +
> +#ifdef TCGETS2
> +    rc = ioctl(fd, TCGETS2, &tio);
> +#else
> +    rc = ioctl(fd, TCGETS, &tio);
> +#endif
> +    if (rc) {
> +        perror("TCGETS");
> +        close(fd);
> +        exit(EXIT_FAILURE);
> +    }
> +
> +    printf("%u\en", tio.c_ospeed);
> +
> +    if (argc == 3) {
> +        tio.c_cflag &= ~CBAUD;
> +        tio.c_cflag |= BOTHER;
> +        tio.c_ospeed = tio.c_ispeed = atoi(argv[2]);
> +
> +#ifdef TCSETS2
> +        rc = ioctl(fd, TCSETS2, &tio);
> +#else
> +        rc = ioctl(fd, TCSETS, &tio);
> +#endif
> +        if (rc) {
> +            perror("TCSETS");
> +            close(fd);
> +            exit(EXIT_FAILURE);
> +        }
> +    }
> +
> +    close(fd);
> +    exit(EXIT_SUCCESS);
> +#endif
> +}
> +.EE
>  .SH SEE ALSO
>  .BR ldattach (1),
>  .BR ioctl (2),
> -- 
> 2.20.1
> 

Re: [PATCH v3] ioctl_tty.2: Add example how to get or set baudrate on the serial port

[Greg Kroah-Hartman via Libc-alpha]

On Thu, Aug 05, 2021 at 12:08:08AM +0200, Pali Rohár wrote:
> + linux-serial
> + Greg
> 
> Greg, could I ask you for reviewing this documentation manpage patch?

If it is submitted in a format I can review, sure (i.e. not top-post...)

But I will dig down below to say one thing...

> 
> On Sunday 01 August 2021 15:51:45 Pali Rohár wrote:
> > Signed-off-by: Pali Rohár <pali@kernel.org>
> > 
> > ---
> > Changes in v3:
> > * Check support for custom baudrate only based on BOTHER macro
> > * Use TCGETS/TCSETS/termios when TCGETS2/TCSETS2/termios2 is not available
> > 
> > Changes in v2:
> > * Use \e for backslash
> > * Use exit(EXIT_*) instead of return num
> > * Sort includes
> > * Add comment about possible fallback
> > ---
> > 
> > Hello Alejandro!
> > 
> > I found out that this stuff is more complicated as I originally thought.
> > And seems that additional documentation on this topic is needed...
> > 
> > For setting custom baudrate it is needed to set BOTHER flag in c_cflag
> > field and baudrate value itself in c_ospeed and c_ispeed fields.
> > 
> > So when BOTHER flag is not provided by <asm/termbits.h> then setting custom
> > baudrate is not possible, fields c_ospeed and c_ispeed do not exist (and
> > only some predefined Bnnn baudrate values are supported). This applies when
> > compiling application with older version of header files (prior support for
> > custom baudrate was introduced into header files).
> > 
> > First caveat: BOTHER constant is different for different architectures.
> > So it is not possible to provide fallback #ifndef..#define BOTHER.
> > 
> > And now the biggest issue: Some architectures have these c_ospeed and
> > c_ispeed fields in struct termios and some in struct termios2.
> > 
> > TCGETS/TCSETS ioctls use struct termios and TCGETS/TCSETS2 use
> > struct termios2.
> > 
> > Some architectures (e.g. amd64) provide both struct termios and struct
> > termios2, but c_ospeed and c_ispeed are only in struct termios2.
> > 
> > Some other architectures (e.g. alpha) provide both struct termios and struct
> > termios2 and both have c_ospeed and c_ispeed fields.
> > 
> > And some other architectures (e.g. powerpc) provide only struct termios
> > (no struct termios2) and it has c_ospeed and c_ispeed fields.
> > 
> > So basically to support all architectures it is needed to use
> > struct termios2 when TCGETS2/TCSETS2 is supported. Otherwise it is needed
> > to use struct termios with TCGETS/TCSETS (case for e.g. powerpc).
> > 
> > I updated v3 patch to handle this logic.
> > ---
> >  man2/ioctl_tty.2 | 73 ++++++++++++++++++++++++++++++++++++++++++++++++
> >  1 file changed, 73 insertions(+)
> > 
> > diff --git a/man2/ioctl_tty.2 b/man2/ioctl_tty.2
> > index 3020f9984872..d83cbd17225b 100644
> > --- a/man2/ioctl_tty.2
> > +++ b/man2/ioctl_tty.2
> > @@ -764,6 +764,79 @@ main(void)
> >      close(fd);
> >  }
> >  .EE
> > +.PP
> > +Get or set arbitrary baudrate on the serial port.
> > +.PP
> > +.EX
> > +#include <asm/termbits.h>
> > +#include <fcntl.h>
> > +#include <stdio.h>
> > +#include <stdlib.h>
> > +#include <sys/ioctl.h>
> > +#include <sys/types.h>
> > +#include <unistd.h>
> > +
> > +int
> > +main(int argc, char *argv[])
> > +{
> > +#ifndef BOTHER
> > +    fprintf(stderr, "BOTHER is unsupported\en");
> > +    /* Program may fallback to TCGETS/TCSETS with Bnnn constants */
> > +    exit(EXIT_FAILURE);

So this is a BOTHER test only?

What is the goal of this program?  Don't throw a bunch of #ifdef in here
for no good reason.  These options should all be present on all normal
kernels, why wouldn't they be?

thanks,

greg k-h

Re: [PATCH v3] ioctl_tty.2: Add example how to get or set baudrate on the serial port

[Pali Rohár via Libc-alpha]

On Thursday 05 August 2021 07:52:03 Greg Kroah-Hartman wrote:
> On Thu, Aug 05, 2021 at 12:08:08AM +0200, Pali Rohár wrote:
> > + linux-serial
> > + Greg
> > 
> > Greg, could I ask you for reviewing this documentation manpage patch?
> 
> If it is submitted in a format I can review, sure (i.e. not top-post...)
> 
> But I will dig down below to say one thing...
> 
> > 
> > On Sunday 01 August 2021 15:51:45 Pali Rohár wrote:
> > > Signed-off-by: Pali Rohár <pali@kernel.org>
> > > 
> > > ---
> > > Changes in v3:
> > > * Check support for custom baudrate only based on BOTHER macro
> > > * Use TCGETS/TCSETS/termios when TCGETS2/TCSETS2/termios2 is not available
> > > 
> > > Changes in v2:
> > > * Use \e for backslash
> > > * Use exit(EXIT_*) instead of return num
> > > * Sort includes
> > > * Add comment about possible fallback
> > > ---
> > > 
> > > Hello Alejandro!
> > > 
> > > I found out that this stuff is more complicated as I originally thought.
> > > And seems that additional documentation on this topic is needed...
> > > 
> > > For setting custom baudrate it is needed to set BOTHER flag in c_cflag
> > > field and baudrate value itself in c_ospeed and c_ispeed fields.
> > > 
> > > So when BOTHER flag is not provided by <asm/termbits.h> then setting custom
> > > baudrate is not possible, fields c_ospeed and c_ispeed do not exist (and
> > > only some predefined Bnnn baudrate values are supported). This applies when
> > > compiling application with older version of header files (prior support for
> > > custom baudrate was introduced into header files).
> > > 
> > > First caveat: BOTHER constant is different for different architectures.
> > > So it is not possible to provide fallback #ifndef..#define BOTHER.
> > > 
> > > And now the biggest issue: Some architectures have these c_ospeed and
> > > c_ispeed fields in struct termios and some in struct termios2.
> > > 
> > > TCGETS/TCSETS ioctls use struct termios and TCGETS/TCSETS2 use
> > > struct termios2.
> > > 
> > > Some architectures (e.g. amd64) provide both struct termios and struct
> > > termios2, but c_ospeed and c_ispeed are only in struct termios2.
> > > 
> > > Some other architectures (e.g. alpha) provide both struct termios and struct
> > > termios2 and both have c_ospeed and c_ispeed fields.
> > > 
> > > And some other architectures (e.g. powerpc) provide only struct termios
> > > (no struct termios2) and it has c_ospeed and c_ispeed fields.
> > > 
> > > So basically to support all architectures it is needed to use
> > > struct termios2 when TCGETS2/TCSETS2 is supported. Otherwise it is needed
> > > to use struct termios with TCGETS/TCSETS (case for e.g. powerpc).
> > > 
> > > I updated v3 patch to handle this logic.
> > > ---
> > >  man2/ioctl_tty.2 | 73 ++++++++++++++++++++++++++++++++++++++++++++++++
> > >  1 file changed, 73 insertions(+)
> > > 
> > > diff --git a/man2/ioctl_tty.2 b/man2/ioctl_tty.2
> > > index 3020f9984872..d83cbd17225b 100644
> > > --- a/man2/ioctl_tty.2
> > > +++ b/man2/ioctl_tty.2
> > > @@ -764,6 +764,79 @@ main(void)
> > >      close(fd);
> > >  }
> > >  .EE
> > > +.PP
> > > +Get or set arbitrary baudrate on the serial port.
> > > +.PP
> > > +.EX
> > > +#include <asm/termbits.h>
> > > +#include <fcntl.h>
> > > +#include <stdio.h>
> > > +#include <stdlib.h>
> > > +#include <sys/ioctl.h>
> > > +#include <sys/types.h>
> > > +#include <unistd.h>
> > > +
> > > +int
> > > +main(int argc, char *argv[])
> > > +{
> > > +#ifndef BOTHER
> > > +    fprintf(stderr, "BOTHER is unsupported\en");
> > > +    /* Program may fallback to TCGETS/TCSETS with Bnnn constants */
> > > +    exit(EXIT_FAILURE);
> 
> So this is a BOTHER test only?

Yes.

> What is the goal of this program?  Don't throw a bunch of #ifdef in here
> for no good reason.  These options should all be present on all normal
> kernels, why wouldn't they be?

I wanted to provide complete example which compiles fine on all Linux
systems, even with older include header files. I do not know right now
in which kernel version was introduced BOTHER support for all
architectures.

If BOHTER is not supported then it is possible to still use Bnnn
constants to get / set baudrate. Just it is needed to write long code
for converting number to suitable Bnnn constant.

Do you think that this BOTHER check is not useful in this case?

> thanks,
> 
> greg k-h

Re: [PATCH v3] ioctl_tty.2: Add example how to get or set baudrate on the serial port

[Greg Kroah-Hartman via Libc-alpha]

On Thu, Aug 05, 2021 at 10:22:43AM +0200, Pali Rohár wrote:
> On Thursday 05 August 2021 07:52:03 Greg Kroah-Hartman wrote:
> > On Thu, Aug 05, 2021 at 12:08:08AM +0200, Pali Rohár wrote:
> > > + linux-serial
> > > + Greg
> > > 
> > > Greg, could I ask you for reviewing this documentation manpage patch?
> > 
> > If it is submitted in a format I can review, sure (i.e. not top-post...)
> > 
> > But I will dig down below to say one thing...
> > 
> > > 
> > > On Sunday 01 August 2021 15:51:45 Pali Rohár wrote:
> > > > Signed-off-by: Pali Rohár <pali@kernel.org>
> > > > 
> > > > ---
> > > > Changes in v3:
> > > > * Check support for custom baudrate only based on BOTHER macro
> > > > * Use TCGETS/TCSETS/termios when TCGETS2/TCSETS2/termios2 is not available
> > > > 
> > > > Changes in v2:
> > > > * Use \e for backslash
> > > > * Use exit(EXIT_*) instead of return num
> > > > * Sort includes
> > > > * Add comment about possible fallback
> > > > ---
> > > > 
> > > > Hello Alejandro!
> > > > 
> > > > I found out that this stuff is more complicated as I originally thought.
> > > > And seems that additional documentation on this topic is needed...
> > > > 
> > > > For setting custom baudrate it is needed to set BOTHER flag in c_cflag
> > > > field and baudrate value itself in c_ospeed and c_ispeed fields.
> > > > 
> > > > So when BOTHER flag is not provided by <asm/termbits.h> then setting custom
> > > > baudrate is not possible, fields c_ospeed and c_ispeed do not exist (and
> > > > only some predefined Bnnn baudrate values are supported). This applies when
> > > > compiling application with older version of header files (prior support for
> > > > custom baudrate was introduced into header files).
> > > > 
> > > > First caveat: BOTHER constant is different for different architectures.
> > > > So it is not possible to provide fallback #ifndef..#define BOTHER.
> > > > 
> > > > And now the biggest issue: Some architectures have these c_ospeed and
> > > > c_ispeed fields in struct termios and some in struct termios2.
> > > > 
> > > > TCGETS/TCSETS ioctls use struct termios and TCGETS/TCSETS2 use
> > > > struct termios2.
> > > > 
> > > > Some architectures (e.g. amd64) provide both struct termios and struct
> > > > termios2, but c_ospeed and c_ispeed are only in struct termios2.
> > > > 
> > > > Some other architectures (e.g. alpha) provide both struct termios and struct
> > > > termios2 and both have c_ospeed and c_ispeed fields.
> > > > 
> > > > And some other architectures (e.g. powerpc) provide only struct termios
> > > > (no struct termios2) and it has c_ospeed and c_ispeed fields.
> > > > 
> > > > So basically to support all architectures it is needed to use
> > > > struct termios2 when TCGETS2/TCSETS2 is supported. Otherwise it is needed
> > > > to use struct termios with TCGETS/TCSETS (case for e.g. powerpc).
> > > > 
> > > > I updated v3 patch to handle this logic.
> > > > ---
> > > >  man2/ioctl_tty.2 | 73 ++++++++++++++++++++++++++++++++++++++++++++++++
> > > >  1 file changed, 73 insertions(+)
> > > > 
> > > > diff --git a/man2/ioctl_tty.2 b/man2/ioctl_tty.2
> > > > index 3020f9984872..d83cbd17225b 100644
> > > > --- a/man2/ioctl_tty.2
> > > > +++ b/man2/ioctl_tty.2
> > > > @@ -764,6 +764,79 @@ main(void)
> > > >      close(fd);
> > > >  }
> > > >  .EE
> > > > +.PP
> > > > +Get or set arbitrary baudrate on the serial port.
> > > > +.PP
> > > > +.EX
> > > > +#include <asm/termbits.h>
> > > > +#include <fcntl.h>
> > > > +#include <stdio.h>
> > > > +#include <stdlib.h>
> > > > +#include <sys/ioctl.h>
> > > > +#include <sys/types.h>
> > > > +#include <unistd.h>
> > > > +
> > > > +int
> > > > +main(int argc, char *argv[])
> > > > +{
> > > > +#ifndef BOTHER
> > > > +    fprintf(stderr, "BOTHER is unsupported\en");
> > > > +    /* Program may fallback to TCGETS/TCSETS with Bnnn constants */
> > > > +    exit(EXIT_FAILURE);
> > 
> > So this is a BOTHER test only?
> 
> Yes.
> 
> > What is the goal of this program?  Don't throw a bunch of #ifdef in here
> > for no good reason.  These options should all be present on all normal
> > kernels, why wouldn't they be?
> 
> I wanted to provide complete example which compiles fine on all Linux
> systems, even with older include header files. I do not know right now
> in which kernel version was introduced BOTHER support for all
> architectures.

We have all of the kernel source in a tool that would allow you to to
determine this quite easily :)

> If BOHTER is not supported then it is possible to still use Bnnn
> constants to get / set baudrate. Just it is needed to write long code
> for converting number to suitable Bnnn constant.
> 
> Do you think that this BOTHER check is not useful in this case?

I think you should provide an example of how to use BOTHER, yes, as it
is hard to find good examples out there as they keep floating around.

Here's one that I point people to a lot:
	https://github.com/GrantEdwards/Linux-arbitrary-baud

Make the example code easy to follow.

Also, you forgot a license for this code, that is required if you want
people to use it...

thanks,

greg k-h

Re: [PATCH v3] ioctl_tty.2: Add example how to get or set baudrate on the serial port

[Pali Rohár via Libc-alpha]

On Thursday 05 August 2021 10:30:15 Greg Kroah-Hartman wrote:
> On Thu, Aug 05, 2021 at 10:22:43AM +0200, Pali Rohár wrote:
> > On Thursday 05 August 2021 07:52:03 Greg Kroah-Hartman wrote:
> > > On Thu, Aug 05, 2021 at 12:08:08AM +0200, Pali Rohár wrote:
> > > > + linux-serial
> > > > + Greg
> > > > 
> > > > Greg, could I ask you for reviewing this documentation manpage patch?
> > > 
> > > If it is submitted in a format I can review, sure (i.e. not top-post...)
> > > 
> > > But I will dig down below to say one thing...
> > > 
> > > > 
> > > > On Sunday 01 August 2021 15:51:45 Pali Rohár wrote:
> > > > > Signed-off-by: Pali Rohár <pali@kernel.org>
> > > > > 
> > > > > ---
> > > > > Changes in v3:
> > > > > * Check support for custom baudrate only based on BOTHER macro
> > > > > * Use TCGETS/TCSETS/termios when TCGETS2/TCSETS2/termios2 is not available
> > > > > 
> > > > > Changes in v2:
> > > > > * Use \e for backslash
> > > > > * Use exit(EXIT_*) instead of return num
> > > > > * Sort includes
> > > > > * Add comment about possible fallback
> > > > > ---
> > > > > 
> > > > > Hello Alejandro!
> > > > > 
> > > > > I found out that this stuff is more complicated as I originally thought.
> > > > > And seems that additional documentation on this topic is needed...
> > > > > 
> > > > > For setting custom baudrate it is needed to set BOTHER flag in c_cflag
> > > > > field and baudrate value itself in c_ospeed and c_ispeed fields.
> > > > > 
> > > > > So when BOTHER flag is not provided by <asm/termbits.h> then setting custom
> > > > > baudrate is not possible, fields c_ospeed and c_ispeed do not exist (and
> > > > > only some predefined Bnnn baudrate values are supported). This applies when
> > > > > compiling application with older version of header files (prior support for
> > > > > custom baudrate was introduced into header files).
> > > > > 
> > > > > First caveat: BOTHER constant is different for different architectures.
> > > > > So it is not possible to provide fallback #ifndef..#define BOTHER.
> > > > > 
> > > > > And now the biggest issue: Some architectures have these c_ospeed and
> > > > > c_ispeed fields in struct termios and some in struct termios2.
> > > > > 
> > > > > TCGETS/TCSETS ioctls use struct termios and TCGETS/TCSETS2 use
> > > > > struct termios2.
> > > > > 
> > > > > Some architectures (e.g. amd64) provide both struct termios and struct
> > > > > termios2, but c_ospeed and c_ispeed are only in struct termios2.
> > > > > 
> > > > > Some other architectures (e.g. alpha) provide both struct termios and struct
> > > > > termios2 and both have c_ospeed and c_ispeed fields.
> > > > > 
> > > > > And some other architectures (e.g. powerpc) provide only struct termios
> > > > > (no struct termios2) and it has c_ospeed and c_ispeed fields.
> > > > > 
> > > > > So basically to support all architectures it is needed to use
> > > > > struct termios2 when TCGETS2/TCSETS2 is supported. Otherwise it is needed
> > > > > to use struct termios with TCGETS/TCSETS (case for e.g. powerpc).
> > > > > 
> > > > > I updated v3 patch to handle this logic.
> > > > > ---
> > > > >  man2/ioctl_tty.2 | 73 ++++++++++++++++++++++++++++++++++++++++++++++++
> > > > >  1 file changed, 73 insertions(+)
> > > > > 
> > > > > diff --git a/man2/ioctl_tty.2 b/man2/ioctl_tty.2
> > > > > index 3020f9984872..d83cbd17225b 100644
> > > > > --- a/man2/ioctl_tty.2
> > > > > +++ b/man2/ioctl_tty.2
> > > > > @@ -764,6 +764,79 @@ main(void)
> > > > >      close(fd);
> > > > >  }
> > > > >  .EE
> > > > > +.PP
> > > > > +Get or set arbitrary baudrate on the serial port.
> > > > > +.PP
> > > > > +.EX
> > > > > +#include <asm/termbits.h>
> > > > > +#include <fcntl.h>
> > > > > +#include <stdio.h>
> > > > > +#include <stdlib.h>
> > > > > +#include <sys/ioctl.h>
> > > > > +#include <sys/types.h>
> > > > > +#include <unistd.h>
> > > > > +
> > > > > +int
> > > > > +main(int argc, char *argv[])
> > > > > +{
> > > > > +#ifndef BOTHER
> > > > > +    fprintf(stderr, "BOTHER is unsupported\en");
> > > > > +    /* Program may fallback to TCGETS/TCSETS with Bnnn constants */
> > > > > +    exit(EXIT_FAILURE);
> > > 
> > > So this is a BOTHER test only?
> > 
> > Yes.
> > 
> > > What is the goal of this program?  Don't throw a bunch of #ifdef in here
> > > for no good reason.  These options should all be present on all normal
> > > kernels, why wouldn't they be?
> > 
> > I wanted to provide complete example which compiles fine on all Linux
> > systems, even with older include header files. I do not know right now
> > in which kernel version was introduced BOTHER support for all
> > architectures.
> 
> We have all of the kernel source in a tool that would allow you to to
> determine this quite easily :)
> 
> > If BOHTER is not supported then it is possible to still use Bnnn
> > constants to get / set baudrate. Just it is needed to write long code
> > for converting number to suitable Bnnn constant.
> > 
> > Do you think that this BOTHER check is not useful in this case?
> 
> I think you should provide an example of how to use BOTHER, yes, as it
> is hard to find good examples out there as they keep floating around.

Exactly, and this is one of the reason why I sent this my patch for
ioctl_tty.2.

> Here's one that I point people to a lot:
> 	https://github.com/GrantEdwards/Linux-arbitrary-baud

I'm looking at this example at it has lot of problems:

* Does not compile on powerpc (see explanation above).
* Does not include <sys/ioctl.h> and instead provide open-coded
  declaration of ioctl: int ioctl(int d, int request, ...);
* Does not handle case when TCGETS/TCSETS contains t.c_ospeed

In my opinion include header files should be used instead of writing own
declaration of functions.

> Make the example code easy to follow.
> 
> Also, you forgot a license for this code, that is required if you want
> people to use it...

Hm... I do not see any license in other manpage examples. Does not apply
for it global license defined in ioctl_tty.2 file?

Alejandro: How do you handle licences in other examples?

> thanks,
> 
> greg k-h

Re: [PATCH v3] ioctl_tty.2: Add example how to get or set baudrate on the serial port

[Greg Kroah-Hartman via Libc-alpha]

On Thu, Aug 05, 2021 at 10:44:10AM +0200, Pali Rohár wrote:
> On Thursday 05 August 2021 10:30:15 Greg Kroah-Hartman wrote:
> > On Thu, Aug 05, 2021 at 10:22:43AM +0200, Pali Rohár wrote:
> > > On Thursday 05 August 2021 07:52:03 Greg Kroah-Hartman wrote:
> > > > On Thu, Aug 05, 2021 at 12:08:08AM +0200, Pali Rohár wrote:
> > > > > + linux-serial
> > > > > + Greg
> > > > > 
> > > > > Greg, could I ask you for reviewing this documentation manpage patch?
> > > > 
> > > > If it is submitted in a format I can review, sure (i.e. not top-post...)
> > > > 
> > > > But I will dig down below to say one thing...
> > > > 
> > > > > 
> > > > > On Sunday 01 August 2021 15:51:45 Pali Rohár wrote:
> > > > > > Signed-off-by: Pali Rohár <pali@kernel.org>
> > > > > > 
> > > > > > ---
> > > > > > Changes in v3:
> > > > > > * Check support for custom baudrate only based on BOTHER macro
> > > > > > * Use TCGETS/TCSETS/termios when TCGETS2/TCSETS2/termios2 is not available
> > > > > > 
> > > > > > Changes in v2:
> > > > > > * Use \e for backslash
> > > > > > * Use exit(EXIT_*) instead of return num
> > > > > > * Sort includes
> > > > > > * Add comment about possible fallback
> > > > > > ---
> > > > > > 
> > > > > > Hello Alejandro!
> > > > > > 
> > > > > > I found out that this stuff is more complicated as I originally thought.
> > > > > > And seems that additional documentation on this topic is needed...
> > > > > > 
> > > > > > For setting custom baudrate it is needed to set BOTHER flag in c_cflag
> > > > > > field and baudrate value itself in c_ospeed and c_ispeed fields.
> > > > > > 
> > > > > > So when BOTHER flag is not provided by <asm/termbits.h> then setting custom
> > > > > > baudrate is not possible, fields c_ospeed and c_ispeed do not exist (and
> > > > > > only some predefined Bnnn baudrate values are supported). This applies when
> > > > > > compiling application with older version of header files (prior support for
> > > > > > custom baudrate was introduced into header files).
> > > > > > 
> > > > > > First caveat: BOTHER constant is different for different architectures.
> > > > > > So it is not possible to provide fallback #ifndef..#define BOTHER.
> > > > > > 
> > > > > > And now the biggest issue: Some architectures have these c_ospeed and
> > > > > > c_ispeed fields in struct termios and some in struct termios2.
> > > > > > 
> > > > > > TCGETS/TCSETS ioctls use struct termios and TCGETS/TCSETS2 use
> > > > > > struct termios2.
> > > > > > 
> > > > > > Some architectures (e.g. amd64) provide both struct termios and struct
> > > > > > termios2, but c_ospeed and c_ispeed are only in struct termios2.
> > > > > > 
> > > > > > Some other architectures (e.g. alpha) provide both struct termios and struct
> > > > > > termios2 and both have c_ospeed and c_ispeed fields.
> > > > > > 
> > > > > > And some other architectures (e.g. powerpc) provide only struct termios
> > > > > > (no struct termios2) and it has c_ospeed and c_ispeed fields.
> > > > > > 
> > > > > > So basically to support all architectures it is needed to use
> > > > > > struct termios2 when TCGETS2/TCSETS2 is supported. Otherwise it is needed
> > > > > > to use struct termios with TCGETS/TCSETS (case for e.g. powerpc).
> > > > > > 
> > > > > > I updated v3 patch to handle this logic.
> > > > > > ---
> > > > > >  man2/ioctl_tty.2 | 73 ++++++++++++++++++++++++++++++++++++++++++++++++
> > > > > >  1 file changed, 73 insertions(+)
> > > > > > 
> > > > > > diff --git a/man2/ioctl_tty.2 b/man2/ioctl_tty.2
> > > > > > index 3020f9984872..d83cbd17225b 100644
> > > > > > --- a/man2/ioctl_tty.2
> > > > > > +++ b/man2/ioctl_tty.2
> > > > > > @@ -764,6 +764,79 @@ main(void)
> > > > > >      close(fd);
> > > > > >  }
> > > > > >  .EE
> > > > > > +.PP
> > > > > > +Get or set arbitrary baudrate on the serial port.
> > > > > > +.PP
> > > > > > +.EX
> > > > > > +#include <asm/termbits.h>
> > > > > > +#include <fcntl.h>
> > > > > > +#include <stdio.h>
> > > > > > +#include <stdlib.h>
> > > > > > +#include <sys/ioctl.h>
> > > > > > +#include <sys/types.h>
> > > > > > +#include <unistd.h>
> > > > > > +
> > > > > > +int
> > > > > > +main(int argc, char *argv[])
> > > > > > +{
> > > > > > +#ifndef BOTHER
> > > > > > +    fprintf(stderr, "BOTHER is unsupported\en");
> > > > > > +    /* Program may fallback to TCGETS/TCSETS with Bnnn constants */
> > > > > > +    exit(EXIT_FAILURE);
> > > > 
> > > > So this is a BOTHER test only?
> > > 
> > > Yes.
> > > 
> > > > What is the goal of this program?  Don't throw a bunch of #ifdef in here
> > > > for no good reason.  These options should all be present on all normal
> > > > kernels, why wouldn't they be?
> > > 
> > > I wanted to provide complete example which compiles fine on all Linux
> > > systems, even with older include header files. I do not know right now
> > > in which kernel version was introduced BOTHER support for all
> > > architectures.
> > 
> > We have all of the kernel source in a tool that would allow you to to
> > determine this quite easily :)
> > 
> > > If BOHTER is not supported then it is possible to still use Bnnn
> > > constants to get / set baudrate. Just it is needed to write long code
> > > for converting number to suitable Bnnn constant.
> > > 
> > > Do you think that this BOTHER check is not useful in this case?
> > 
> > I think you should provide an example of how to use BOTHER, yes, as it
> > is hard to find good examples out there as they keep floating around.
> 
> Exactly, and this is one of the reason why I sent this my patch for
> ioctl_tty.2.
> 
> > Here's one that I point people to a lot:
> > 	https://github.com/GrantEdwards/Linux-arbitrary-baud
> 
> I'm looking at this example at it has lot of problems:
> 
> * Does not compile on powerpc (see explanation above).
> * Does not include <sys/ioctl.h> and instead provide open-coded
>   declaration of ioctl: int ioctl(int d, int request, ...);
> * Does not handle case when TCGETS/TCSETS contains t.c_ospeed

Great, then fix all of that :)

> In my opinion include header files should be used instead of writing own
> declaration of functions.

I agree.

> > Make the example code easy to follow.
> > 
> > Also, you forgot a license for this code, that is required if you want
> > people to use it...
> 
> Hm... I do not see any license in other manpage examples. Does not apply
> for it global license defined in ioctl_tty.2 file?

That does not mean you do not need it.

thanks,

greg k-h

Re: [PATCH v3] ioctl_tty.2: Add example how to get or set baudrate on the serial port

[Pali Rohár via Libc-alpha]

On Thursday 05 August 2021 10:50:31 Greg Kroah-Hartman wrote:
> On Thu, Aug 05, 2021 at 10:44:10AM +0200, Pali Rohár wrote:
> > On Thursday 05 August 2021 10:30:15 Greg Kroah-Hartman wrote:
> > > On Thu, Aug 05, 2021 at 10:22:43AM +0200, Pali Rohár wrote:
> > > > On Thursday 05 August 2021 07:52:03 Greg Kroah-Hartman wrote:
> > > > > On Thu, Aug 05, 2021 at 12:08:08AM +0200, Pali Rohár wrote:
> > > > > > + linux-serial
> > > > > > + Greg
> > > > > > 
> > > > > > Greg, could I ask you for reviewing this documentation manpage patch?
> > > > > 
> > > > > If it is submitted in a format I can review, sure (i.e. not top-post...)
> > > > > 
> > > > > But I will dig down below to say one thing...
> > > > > 
> > > > > > 
> > > > > > On Sunday 01 August 2021 15:51:45 Pali Rohár wrote:
> > > > > > > Signed-off-by: Pali Rohár <pali@kernel.org>
> > > > > > > 
> > > > > > > ---
> > > > > > > Changes in v3:
> > > > > > > * Check support for custom baudrate only based on BOTHER macro
> > > > > > > * Use TCGETS/TCSETS/termios when TCGETS2/TCSETS2/termios2 is not available
> > > > > > > 
> > > > > > > Changes in v2:
> > > > > > > * Use \e for backslash
> > > > > > > * Use exit(EXIT_*) instead of return num
> > > > > > > * Sort includes
> > > > > > > * Add comment about possible fallback
> > > > > > > ---
> > > > > > > 
> > > > > > > Hello Alejandro!
> > > > > > > 
> > > > > > > I found out that this stuff is more complicated as I originally thought.
> > > > > > > And seems that additional documentation on this topic is needed...
> > > > > > > 
> > > > > > > For setting custom baudrate it is needed to set BOTHER flag in c_cflag
> > > > > > > field and baudrate value itself in c_ospeed and c_ispeed fields.
> > > > > > > 
> > > > > > > So when BOTHER flag is not provided by <asm/termbits.h> then setting custom
> > > > > > > baudrate is not possible, fields c_ospeed and c_ispeed do not exist (and
> > > > > > > only some predefined Bnnn baudrate values are supported). This applies when
> > > > > > > compiling application with older version of header files (prior support for
> > > > > > > custom baudrate was introduced into header files).
> > > > > > > 
> > > > > > > First caveat: BOTHER constant is different for different architectures.
> > > > > > > So it is not possible to provide fallback #ifndef..#define BOTHER.
> > > > > > > 
> > > > > > > And now the biggest issue: Some architectures have these c_ospeed and
> > > > > > > c_ispeed fields in struct termios and some in struct termios2.
> > > > > > > 
> > > > > > > TCGETS/TCSETS ioctls use struct termios and TCGETS/TCSETS2 use
> > > > > > > struct termios2.
> > > > > > > 
> > > > > > > Some architectures (e.g. amd64) provide both struct termios and struct
> > > > > > > termios2, but c_ospeed and c_ispeed are only in struct termios2.
> > > > > > > 
> > > > > > > Some other architectures (e.g. alpha) provide both struct termios and struct
> > > > > > > termios2 and both have c_ospeed and c_ispeed fields.
> > > > > > > 
> > > > > > > And some other architectures (e.g. powerpc) provide only struct termios
> > > > > > > (no struct termios2) and it has c_ospeed and c_ispeed fields.
> > > > > > > 
> > > > > > > So basically to support all architectures it is needed to use
> > > > > > > struct termios2 when TCGETS2/TCSETS2 is supported. Otherwise it is needed
> > > > > > > to use struct termios with TCGETS/TCSETS (case for e.g. powerpc).
> > > > > > > 
> > > > > > > I updated v3 patch to handle this logic.
> > > > > > > ---
> > > > > > >  man2/ioctl_tty.2 | 73 ++++++++++++++++++++++++++++++++++++++++++++++++
> > > > > > >  1 file changed, 73 insertions(+)
> > > > > > > 
> > > > > > > diff --git a/man2/ioctl_tty.2 b/man2/ioctl_tty.2
> > > > > > > index 3020f9984872..d83cbd17225b 100644
> > > > > > > --- a/man2/ioctl_tty.2
> > > > > > > +++ b/man2/ioctl_tty.2
> > > > > > > @@ -764,6 +764,79 @@ main(void)
> > > > > > >      close(fd);
> > > > > > >  }
> > > > > > >  .EE
> > > > > > > +.PP
> > > > > > > +Get or set arbitrary baudrate on the serial port.
> > > > > > > +.PP
> > > > > > > +.EX
> > > > > > > +#include <asm/termbits.h>
> > > > > > > +#include <fcntl.h>
> > > > > > > +#include <stdio.h>
> > > > > > > +#include <stdlib.h>
> > > > > > > +#include <sys/ioctl.h>
> > > > > > > +#include <sys/types.h>
> > > > > > > +#include <unistd.h>
> > > > > > > +
> > > > > > > +int
> > > > > > > +main(int argc, char *argv[])
> > > > > > > +{
> > > > > > > +#ifndef BOTHER
> > > > > > > +    fprintf(stderr, "BOTHER is unsupported\en");
> > > > > > > +    /* Program may fallback to TCGETS/TCSETS with Bnnn constants */
> > > > > > > +    exit(EXIT_FAILURE);
> > > > > 
> > > > > So this is a BOTHER test only?
> > > > 
> > > > Yes.
> > > > 
> > > > > What is the goal of this program?  Don't throw a bunch of #ifdef in here
> > > > > for no good reason.  These options should all be present on all normal
> > > > > kernels, why wouldn't they be?
> > > > 
> > > > I wanted to provide complete example which compiles fine on all Linux
> > > > systems, even with older include header files. I do not know right now
> > > > in which kernel version was introduced BOTHER support for all
> > > > architectures.
> > > 
> > > We have all of the kernel source in a tool that would allow you to to
> > > determine this quite easily :)
> > > 
> > > > If BOHTER is not supported then it is possible to still use Bnnn
> > > > constants to get / set baudrate. Just it is needed to write long code
> > > > for converting number to suitable Bnnn constant.
> > > > 
> > > > Do you think that this BOTHER check is not useful in this case?
> > > 
> > > I think you should provide an example of how to use BOTHER, yes, as it
> > > is hard to find good examples out there as they keep floating around.
> > 
> > Exactly, and this is one of the reason why I sent this my patch for
> > ioctl_tty.2.
> > 
> > > Here's one that I point people to a lot:
> > > 	https://github.com/GrantEdwards/Linux-arbitrary-baud
> > 
> > I'm looking at this example at it has lot of problems:
> > 
> > * Does not compile on powerpc (see explanation above).
> > * Does not include <sys/ioctl.h> and instead provide open-coded
> >   declaration of ioctl: int ioctl(int d, int request, ...);
> > * Does not handle case when TCGETS/TCSETS contains t.c_ospeed
> 
> Great, then fix all of that :)

It should have been already in this my patch which provides this
example. That is why I asked for review from other people :-)

> > In my opinion include header files should be used instead of writing own
> > declaration of functions.
> 
> I agree.
> 
> > > Make the example code easy to follow.
> > > 
> > > Also, you forgot a license for this code, that is required if you want
> > > people to use it...
> > 
> > Hm... I do not see any license in other manpage examples. Does not apply
> > for it global license defined in ioctl_tty.2 file?
> 
> That does not mean you do not need it.

I will wait for Alejandro's reaction on this topic as I think he wants
to have all manpages consistent and with the same style, headers, etc...

Re: [PATCH v3] ioctl_tty.2: Add example how to get or set baudrate on the serial port

[Alejandro Colomar (man-pages) via Libc-alpha]

Hi Pali,

On 8/5/21 11:51 AM, Pali Rohár wrote:
>>>> Also, you forgot a license for this code, that is required if you want
>>>> people to use it...
>>>
>>> Hm... I do not see any license in other manpage examples. Does not apply
>>> for it global license defined in ioctl_tty.2 file?
>>
>> That does not mean you do not need it.

I don't know what is the status of the current code examples in terms of 
licensing.

I thought I had seen an SPDX license identifier in one of them some time 
ago, but now I can't find it.

Technically, the pages have a license at the top of each file, which 
isn't printed on the rendered output (the license text doesn't require 
so) (see that text below).

If you want a different license for your example (let's say you want it 
BSD for example), I guess you could add an SPDX line at the top of the 
example for simplicity.

But if your code example adheres to the same license as the rest of the 
page, I guess you don't need to do anything in your patch.

But I'm not sure at all; maybe Michael can tell you more about it.

> 
> I will wait for Alejandro's reaction on this topic as I think he wants
> to have all manpages consistent and with the same style, headers, etc...
> 

Thanks!

Alex


---
$ head -n 26 man7/system_data_types.7
.\" Copyright (c) 2020 by Alejandro Colomar <colomar.6.4.3@gmail.com>
.\" and Copyright (c) 2020 by Michael Kerrisk <mtk.manpages@gmail.com>
.\"
.\" %%%LICENSE_START(VERBATIM)
.\" Permission is granted to make and distribute verbatim copies of this
.\" manual provided the copyright notice and this permission notice are
.\" preserved on all copies.
.\"
.\" Permission is granted to copy and distribute modified versions of this
.\" manual under the conditions for verbatim copying, provided that the
.\" entire resulting derived work is distributed under the terms of a
.\" permission notice identical to this one.
.\"
.\" Since the Linux kernel and libraries are constantly changing, this
.\" manual page may be incorrect or out-of-date.  The author(s) assume no
.\" responsibility for errors or omissions, or for damages resulting from
.\" the use of the information contained herein.  The author(s) may not
.\" have taken the same level of care in the production of this manual,
.\" which is licensed free of charge, as they might when working
.\" professionally.
.\"
.\" Formatted or processed versions of this manual, if unaccompanied by
.\" the source, must acknowledge the copyright and authors of this work.
.\" %%%LICENSE_END
.\"
.\"



-- 
Alejandro Colomar
Linux man-pages comaintainer; https://www.kernel.org/doc/man-pages/
http://www.alejandro-colomar.es/

Re: [PATCH v3] ioctl_tty.2: Add example how to get or set baudrate on the serial port

[Greg Kroah-Hartman via Libc-alpha]

On Thu, Aug 05, 2021 at 05:28:49PM +0200, Alejandro Colomar (man-pages) wrote:
> Hi Pali,
> 
> On 8/5/21 11:51 AM, Pali Rohár wrote:
> > > > > Also, you forgot a license for this code, that is required if you want
> > > > > people to use it...
> > > > 
> > > > Hm... I do not see any license in other manpage examples. Does not apply
> > > > for it global license defined in ioctl_tty.2 file?
> > > 
> > > That does not mean you do not need it.
> 
> I don't know what is the status of the current code examples in terms of
> licensing.
> 
> I thought I had seen an SPDX license identifier in one of them some time
> ago, but now I can't find it.
> 
> Technically, the pages have a license at the top of each file, which isn't
> printed on the rendered output (the license text doesn't require so) (see
> that text below).
> 
> If you want a different license for your example (let's say you want it BSD
> for example), I guess you could add an SPDX line at the top of the example
> for simplicity.
> 
> But if your code example adheres to the same license as the rest of the
> page, I guess you don't need to do anything in your patch.

What is the license of a man page?

What is the license of this page?

And if it is not shown in the code segment itself, that's going to be a
mess, please make it explicit, otherwise no one can ever use any of the
code examples for anything.

thanks,

greg k-h

Licensing example programs in man-pages (was [PATCH v3] ioctl_tty.2: Add example how to get or set baudrate on the serial port)

[Alejandro Colomar (man-pages) via Libc-alpha]

Hi Greg,

On 8/5/21 6:14 PM, Greg Kroah-Hartman wrote:
> On Thu, Aug 05, 2021 at 05:28:49PM +0200, Alejandro Colomar (man-pages) wrote:
>> Hi Pali,
>>
>> On 8/5/21 11:51 AM, Pali Rohár wrote:
>>>>>> Also, you forgot a license for this code, that is required if you want
>>>>>> people to use it...
>>>>>
>>>>> Hm... I do not see any license in other manpage examples. Does not apply
>>>>> for it global license defined in ioctl_tty.2 file?
>>>>
>>>> That does not mean you do not need it.
>>
>> I don't know what is the status of the current code examples in terms of
>> licensing.
>>
>> I thought I had seen an SPDX license identifier in one of them some time
>> ago, but now I can't find it.
>>
>> Technically, the pages have a license at the top of each file, which isn't
>> printed on the rendered output (the license text doesn't require so) (see
>> that text below).
>>
>> If you want a different license for your example (let's say you want it BSD
>> for example), I guess you could add an SPDX line at the top of the example
>> for simplicity.
>>
>> But if your code example adheres to the same license as the rest of the
>> page, I guess you don't need to do anything in your patch.
> 
> What is the license of a man page?

Typically, the one I showed in my last email (the "Verbatim" license").
See <https://www.kernel.org/doc/man-pages/licenses.html>.

> 
> What is the license of this page?

.../linux/man-pages$ head -n8 man2/ioctl_tty.2
.\" Copyright 2002 Walter Harms <walter.harms@informatik.uni-oldenburg.de>
.\" and Andries Brouwer <aeb@cwi.nl>.
.\"
.\" %%%LICENSE_START(GPL_NOVERSION_ONELINE)
.\" Distributed under GPL
.\" %%%LICENSE_END
.\"
.TH IOCTL_TTY 2 2021-03-22 "Linux" "Linux Programmer's Manual"

I'm don't know what GPL_NOVERSION_ONLINE is at all.

CC += Walter, Andries

> 
> And if it is not shown in the code segment itself, that's going to be a
> mess, please make it explicit, otherwise no one can ever use any of the
> code examples for anything.

I'm not against that.  At

However, there's an explicit mention (without any rationale at all, or I 
couldn't find it) in man-pages(7) that the Linux man-pages project 
doesn't use the COPYRIGHT section:

[
DESCRIPTION
        This page describes the conventions that should be employed
        when writing man pages for  the  Linux  man‐pages  project,
        which  documents  the  user‐space API provided by the Linux
        kernel and the GNU C library.  The  project  thus  provides
        most  of the pages in Section 2, many of the pages that ap‐
        pear in Sections 3, 4, and 7, and a few of the  pages  that
        appear  in Sections 1, 5, and 8 of the man pages on a Linux
        system.  The conventions described on this page may also be
        useful for authors writing man pages for other projects.

        [...]

    Sections within a manual page
        The  list  below  shows conventional or suggested sections.
        Most manual pages should include at least  the  highlighted
        sections.   Arrange  a new manual page so that sections are
        placed in the order shown in the list.

        [...]
               COPYRIGHT        [Not used in man‐pages]
] [[man-pages(7)]]

Maybe Michael can provide a rationale for this.

Still, if the code is going to have a different license than the rest of 
the page, it could perfectly have an SPDX comment in the first line of 
the example program.


Thanks,

Alex


-- 
Alejandro Colomar
Linux man-pages comaintainer; https://www.kernel.org/doc/man-pages/
http://www.alejandro-colomar.es/

Re: Licensing example programs in man-pages (was [PATCH v3] ioctl_tty.2: Add example how to get or set baudrate on the serial port)

[Greg Kroah-Hartman via Libc-alpha]

On Thu, Aug 05, 2021 at 06:45:57PM +0200, Alejandro Colomar (man-pages) wrote:
> Hi Greg,
> 
> On 8/5/21 6:14 PM, Greg Kroah-Hartman wrote:
> > On Thu, Aug 05, 2021 at 05:28:49PM +0200, Alejandro Colomar (man-pages) wrote:
> > > Hi Pali,
> > > 
> > > On 8/5/21 11:51 AM, Pali Rohár wrote:
> > > > > > > Also, you forgot a license for this code, that is required if you want
> > > > > > > people to use it...
> > > > > > 
> > > > > > Hm... I do not see any license in other manpage examples. Does not apply
> > > > > > for it global license defined in ioctl_tty.2 file?
> > > > > 
> > > > > That does not mean you do not need it.
> > > 
> > > I don't know what is the status of the current code examples in terms of
> > > licensing.
> > > 
> > > I thought I had seen an SPDX license identifier in one of them some time
> > > ago, but now I can't find it.
> > > 
> > > Technically, the pages have a license at the top of each file, which isn't
> > > printed on the rendered output (the license text doesn't require so) (see
> > > that text below).
> > > 
> > > If you want a different license for your example (let's say you want it BSD
> > > for example), I guess you could add an SPDX line at the top of the example
> > > for simplicity.
> > > 
> > > But if your code example adheres to the same license as the rest of the
> > > page, I guess you don't need to do anything in your patch.
> > 
> > What is the license of a man page?
> 
> Typically, the one I showed in my last email (the "Verbatim" license").
> See <https://www.kernel.org/doc/man-pages/licenses.html>.
> 
> > 
> > What is the license of this page?
> 
> .../linux/man-pages$ head -n8 man2/ioctl_tty.2
> .\" Copyright 2002 Walter Harms <walter.harms@informatik.uni-oldenburg.de>
> .\" and Andries Brouwer <aeb@cwi.nl>.
> .\"
> .\" %%%LICENSE_START(GPL_NOVERSION_ONELINE)
> .\" Distributed under GPL

What version of GPL?

> .\" %%%LICENSE_END
> .\"
> .TH IOCTL_TTY 2 2021-03-22 "Linux" "Linux Programmer's Manual"
> 
> I'm don't know what GPL_NOVERSION_ONLINE is at all.

I would recommend adding proper SPDX markings to all of these files.
Even better, work to make the whole repo REUSE compliant which means
that there is no ambuiguity here.

But, the above license does not show up on the code in the original
example here, and that needs to be present if anyone wants this to be
used.

> Still, if the code is going to have a different license than the rest of the
> page, it could perfectly have an SPDX comment in the first line of the
> example program.

Even if it is different, it should still be present as no one can see
the license of a man page "easily" when reading the documentation
through normal tools.

thanks,

greg k-h

Re: Licensing example programs in man-pages (was [PATCH v3] ioctl_tty.2: Add example how to get or set baudrate on the serial port)

[Alejandro Colomar (man-pages) via Libc-alpha]

Hi Greg, Pali,

Hi GregOn 8/5/21 7:54 PM, Greg Kroah-Hartman wrote:
>>> What is the license of this page?
>>
>> .../linux/man-pages$ head -n8 man2/ioctl_tty.2
>> .\" Copyright 2002 Walter Harms <walter.harms@informatik.uni-oldenburg.de>
>> .\" and Andries Brouwer <aeb@cwi.nl>.
>> .\"
>> .\" %%%LICENSE_START(GPL_NOVERSION_ONELINE)
>> .\" Distributed under GPL
> 
> What version of GPL?

I don't know :/
Maybe v1...

> 
>> .\" %%%LICENSE_END
>> .\"
>> .TH IOCTL_TTY 2 2021-03-22 "Linux" "Linux Programmer's Manual"
>>
>> I'm don't know what GPL_NOVERSION_ONLINE is at all.
> 
> I would recommend adding proper SPDX markings to all of these files.
> Even better, work to make the whole repo REUSE compliant which means
> that there is no ambuiguity here.
> 

Agree.  If Michael has no problems with that, I'll add it to my TODO list.

> But, the above license does not show up on the code in the original
> example here, and that needs to be present if anyone wants this to be
> used.

Yup.

> 
>> Still, if the code is going to have a different license than the rest of the
>> page, it could perfectly have an SPDX comment in the first line of the
>> example program.
> 
> Even if it is different, it should still be present as no one can see
> the license of a man page "easily" when reading the documentation
> through normal tools.

Yup.

> 
> thanks,
> 
> greg k-h
> 

Pali,

If you want to specify a specific license for your code, add 2 SPDX 
lines according to REUSE <https://reuse.software/>.  If not, I'll assume 
that you don't care, and when I fix the pages to show the license (which 
in this case I'm not sure which one will be, maybe GPLv1) your code will 
use that same license.  I'll take care of any necessary adjustments such 
as providing  the license text in the repository; you don't need to do that.


Cheers,

Alex


-- 
Alejandro Colomar
Linux man-pages comaintainer; https://www.kernel.org/doc/man-pages/
http://www.alejandro-colomar.es/

Re: Licensing example programs in man-pages (was [PATCH v3] ioctl_tty.2: Add example how to get or set baudrate on the serial port)

[Pali Rohár via Libc-alpha]

On Friday 06 August 2021 09:22:59 Alejandro Colomar (man-pages) wrote:
> Hi Greg, Pali,
> 
> Hi GregOn 8/5/21 7:54 PM, Greg Kroah-Hartman wrote:
> > > > What is the license of this page?
> > > 
> > > .../linux/man-pages$ head -n8 man2/ioctl_tty.2
> > > .\" Copyright 2002 Walter Harms <walter.harms@informatik.uni-oldenburg.de>
> > > .\" and Andries Brouwer <aeb@cwi.nl>.
> > > .\"
> > > .\" %%%LICENSE_START(GPL_NOVERSION_ONELINE)
> > > .\" Distributed under GPL
> > 
> > What version of GPL?
> 
> I don't know :/
> Maybe v1...
> 
> > 
> > > .\" %%%LICENSE_END
> > > .\"
> > > .TH IOCTL_TTY 2 2021-03-22 "Linux" "Linux Programmer's Manual"
> > > 
> > > I'm don't know what GPL_NOVERSION_ONLINE is at all.
> > 
> > I would recommend adding proper SPDX markings to all of these files.
> > Even better, work to make the whole repo REUSE compliant which means
> > that there is no ambuiguity here.
> > 
> 
> Agree.  If Michael has no problems with that, I'll add it to my TODO list.
> 
> > But, the above license does not show up on the code in the original
> > example here, and that needs to be present if anyone wants this to be
> > used.
> 
> Yup.
> 
> > 
> > > Still, if the code is going to have a different license than the rest of the
> > > page, it could perfectly have an SPDX comment in the first line of the
> > > example program.
> > 
> > Even if it is different, it should still be present as no one can see
> > the license of a man page "easily" when reading the documentation
> > through normal tools.
> 
> Yup.
> 
> > 
> > thanks,
> > 
> > greg k-h
> > 
> 
> Pali,
> 
> If you want to specify a specific license for your code, add 2 SPDX lines
> according to REUSE <https://reuse.software/>.  If not, I'll assume that you
> don't care, and when I fix the pages to show the license (which in this case
> I'm not sure which one will be, maybe GPLv1) your code will use that same
> license.  I'll take care of any necessary adjustments such as providing  the
> license text in the repository; you don't need to do that.

Just do not complicate it and use same license as for other manpages or
examples.

> 
> Cheers,
> 
> Alex
> 
> 
> -- 
> Alejandro Colomar
> Linux man-pages comaintainer; https://www.kernel.org/doc/man-pages/
> http://www.alejandro-colomar.es/

Re: [PATCH v3] ioctl_tty.2: Add example how to get or set baudrate on the serial port

[Alejandro Colomar (man-pages) via Libc-alpha]

Hi Pali,

On 8/1/21 3:51 PM, Pali Rohár wrote:
> Signed-off-by: Pali Rohár <pali@kernel.org>
> 
> ---
> Changes in v3:
> * Check support for custom baudrate only based on BOTHER macro
> * Use TCGETS/TCSETS/termios when TCGETS2/TCSETS2/termios2 is not available
> 
> Changes in v2:
> * Use \e for backslash
> * Use exit(EXIT_*) instead of return num
> * Sort includes
> * Add comment about possible fallback
> ---
> 
> Hello Alejandro!
> 
> I found out that this stuff is more complicated as I originally thought.
> And seems that additional documentation on this topic is needed...
> 
> For setting custom baudrate it is needed to set BOTHER flag in c_cflag
> field and baudrate value itself in c_ospeed and c_ispeed fields.
> 
> So when BOTHER flag is not provided by <asm/termbits.h> then setting custom
> baudrate is not possible, fields c_ospeed and c_ispeed do not exist (and
> only some predefined Bnnn baudrate values are supported). This applies when
> compiling application with older version of header files (prior support for
> custom baudrate was introduced into header files).
> 
> First caveat: BOTHER constant is different for different architectures.
> So it is not possible to provide fallback #ifndef..#define BOTHER.
> 
> And now the biggest issue: Some architectures have these c_ospeed and
> c_ispeed fields in struct termios and some in struct termios2.
> 
> TCGETS/TCSETS ioctls use struct termios and TCGETS/TCSETS2 use
> struct termios2.
> 
> Some architectures (e.g. amd64) provide both struct termios and struct
> termios2, but c_ospeed and c_ispeed are only in struct termios2.
> 
> Some other architectures (e.g. alpha) provide both struct termios and struct
> termios2 and both have c_ospeed and c_ispeed fields.
> 
> And some other architectures (e.g. powerpc) provide only struct termios
> (no struct termios2) and it has c_ospeed and c_ispeed fields.
> 
> So basically to support all architectures it is needed to use
> struct termios2 when TCGETS2/TCSETS2 is supported. Otherwise it is needed
> to use struct termios with TCGETS/TCSETS (case for e.g. powerpc).

When you send v4, please include the above text (or something similar) 
to the commit message.

Thanks,

Alex

> 
> I updated v3 patch to handle this logic.
> ---


-- 
Alejandro Colomar
Linux man-pages comaintainer; https://www.kernel.org/doc/man-pages/
http://www.alejandro-colomar.es/

Re: [PATCH v3] ioctl_tty.2: Add example how to get or set baudrate on the serial port

[Pali Rohár via Libc-alpha]

On Sunday 08 August 2021 10:35:24 Alejandro Colomar (man-pages) wrote:
> Hi Pali,
> 
> On 8/1/21 3:51 PM, Pali Rohár wrote:
> > Signed-off-by: Pali Rohár <pali@kernel.org>
> > 
> > ---
> > Changes in v3:
> > * Check support for custom baudrate only based on BOTHER macro
> > * Use TCGETS/TCSETS/termios when TCGETS2/TCSETS2/termios2 is not available
> > 
> > Changes in v2:
> > * Use \e for backslash
> > * Use exit(EXIT_*) instead of return num
> > * Sort includes
> > * Add comment about possible fallback
> > ---
> > 
> > Hello Alejandro!
> > 
> > I found out that this stuff is more complicated as I originally thought.
> > And seems that additional documentation on this topic is needed...
> > 
> > For setting custom baudrate it is needed to set BOTHER flag in c_cflag
> > field and baudrate value itself in c_ospeed and c_ispeed fields.
> > 
> > So when BOTHER flag is not provided by <asm/termbits.h> then setting custom
> > baudrate is not possible, fields c_ospeed and c_ispeed do not exist (and
> > only some predefined Bnnn baudrate values are supported). This applies when
> > compiling application with older version of header files (prior support for
> > custom baudrate was introduced into header files).
> > 
> > First caveat: BOTHER constant is different for different architectures.
> > So it is not possible to provide fallback #ifndef..#define BOTHER.
> > 
> > And now the biggest issue: Some architectures have these c_ospeed and
> > c_ispeed fields in struct termios and some in struct termios2.
> > 
> > TCGETS/TCSETS ioctls use struct termios and TCGETS/TCSETS2 use
> > struct termios2.
> > 
> > Some architectures (e.g. amd64) provide both struct termios and struct
> > termios2, but c_ospeed and c_ispeed are only in struct termios2.
> > 
> > Some other architectures (e.g. alpha) provide both struct termios and struct
> > termios2 and both have c_ospeed and c_ispeed fields.
> > 
> > And some other architectures (e.g. powerpc) provide only struct termios
> > (no struct termios2) and it has c_ospeed and c_ispeed fields.
> > 
> > So basically to support all architectures it is needed to use
> > struct termios2 when TCGETS2/TCSETS2 is supported. Otherwise it is needed
> > to use struct termios with TCGETS/TCSETS (case for e.g. powerpc).
> 
> When you send v4, please include the above text (or something similar) to
> the commit message.

Hello Alejandro! Sure I will put description into commit message.

Moreover this kind of information should be properly documented into
ioctl_tty.2 manpage itself. But I really do not know in which part. Into
ioctl (and which?)? Or separate paragraph? As it basically describe some
field of struct termios and struct termios2, which are undocumented too.

Do you have some idea or picture how such thing should be properly
documented in man-pages project?

> Thanks,
> 
> Alex
> 
> > 
> > I updated v3 patch to handle this logic.
> > ---
> 
> 
> -- 
> Alejandro Colomar
> Linux man-pages comaintainer; https://www.kernel.org/doc/man-pages/
> http://www.alejandro-colomar.es/

Re: [PATCH v3] ioctl_tty.2: Add example how to get or set baudrate on the serial port

[Alejandro Colomar (man-pages) via Libc-alpha]

Hi Pali,

On 8/8/21 11:05 PM, Pali Rohár wrote:
>> When you send v4, please include the above text (or something similar) to
>> the commit message.
> 
> Hello Alejandro! Sure I will put description into commit message.
> 
> Moreover this kind of information should be properly documented into
> ioctl_tty.2 manpage itself. But I really do not know in which part. Into
> ioctl (and which?)? Or separate paragraph? As it basically describe some
> field of struct termios and struct termios2, which are undocumented too.
> 
> Do you have some idea or picture how such thing should be properly
> documented in man-pages project?

Being documentation for a type,
I think the best place for that is system_data_types(7)
<https://man7.org/linux/man-pages/man7/system_data_types.7.html>.

Do you feel like writing that?
See the thread we started the other day:
<https://lore.kernel.org/linux-man/5e9e1f1a-1e08-59f5-6579-a02c0738b9a4@gmail.com/T/#u>

You can also get some inspiration from other pages that
also define types, like stat(2), and sigevent(7).

Thanks,

Alex


-- 
Alejandro Colomar
Linux man-pages comaintainer; https://www.kernel.org/doc/man-pages/
http://www.alejandro-colomar.es/

[PATCH v4] ioctl_tty.2: Add example how to get or set baudrate on the serial port

[Pali Rohár via Libc-alpha]

Setting custom baudrate for which is not defined Bnnn constant is possible
via BOTHER flag and then filling speed in c_ospeed and c_ispeed fields.

These two fields are either in struct termios or struct termios2. Former
belongs to TCGETS/TCSETS ioctls, latter to TCGETS2/TCSETS2 ioctls.

BOTHER flag with these two fields and new struct termios2 is not supported
by older versions of include header files.

Some architectures (e.g. amd64) provide both struct termios and struct
termios2, but c_ospeed and c_ispeed are only in struct termios2.

Some other architectures (e.g. alpha) provide both struct termios and struct
termios2 and both have c_ospeed and c_ispeed fields.

And some other architectures (e.g. powerpc) provide only struct termios
(no struct termios2) and it has c_ospeed and c_ispeed fields.

So basically to support all architectures it is needed to use
struct termios2 when TCGETS2/TCSETS2 is supported. Otherwise it is needed
to use struct termios with TCGETS/TCSETS (case for e.g. powerpc).

Setting input baudrate is done via IBSHIFT macro.

Signed-off-by: Pali Rohár <pali@kernel.org>

---
Changes in v4:
* Add SPDX-License-Identifier
* Correctly process split baudrates (separate output and input) via IBSHIFT
* Update commit message

Changes in v3:
* Check support for custom baudrate only based on BOTHER macro
* Use TCGETS/TCSETS/termios when TCGETS2/TCSETS2/termios2 is not available

Changes in v2:
* Use \e for backslash
* Use exit(EXIT_*) instead of return num
* Sort includes
* Add comment about possible fallback
---
 man2/ioctl_tty.2 | 100 +++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 100 insertions(+)

diff --git a/man2/ioctl_tty.2 b/man2/ioctl_tty.2
index abfdc1e21fe9..7b2b03ff6757 100644
--- a/man2/ioctl_tty.2
+++ b/man2/ioctl_tty.2
@@ -796,6 +796,106 @@ main(void)
     close(fd);
 }
 .EE
+.PP
+Get or set arbitrary baudrate on the serial port.
+.PP
+.EX
+/* SPDX-License-Identifier: GPL-2.0-or-later */
+
+#include <asm/termbits.h>
+#include <fcntl.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <sys/ioctl.h>
+#include <sys/types.h>
+#include <unistd.h>
+
+int
+main(int argc, char *argv[])
+{
+#ifndef BOTHER
+    fprintf(stderr, "BOTHER is unsupported\en");
+    /* Program may fallback to TCGETS/TCSETS with Bnnn constants */
+    exit(EXIT_FAILURE);
+#else
+    /* Declare tio structure, its type depends on supported ioctl */
+#ifdef TCGETS2
+    struct termios2 tio;
+#else
+    struct termios tio;
+#endif
+    int fd, rc;
+
+    if (argc != 2 && argc != 3 && argc != 4) {
+        fprintf(stderr, "Usage: %s device [output [input] ]\en", argv[0]);
+        exit(EXIT_FAILURE);
+    }
+
+    fd = open(argv[1], O_RDWR | O_NONBLOCK | O_NOCTTY);
+    if (fd < 0) {
+        perror("open");
+        exit(EXIT_FAILURE);
+    }
+
+    /* Get the current serial port settings via supported ioctl */
+#ifdef TCGETS2
+    rc = ioctl(fd, TCGETS2, &tio);
+#else
+    rc = ioctl(fd, TCGETS, &tio);
+#endif
+    if (rc) {
+        perror("TCGETS");
+        close(fd);
+        exit(EXIT_FAILURE);
+    }
+
+    /* Change baud rate when more arguments were provided */
+    if (argc == 3 || argc == 4) {
+        /* Clear the current output baud rate and fill a new value */
+        tio.c_cflag &= ~CBAUD;
+        tio.c_cflag |= BOTHER;
+        tio.c_ospeed = atoi(argv[2]);
+
+        /* Clear the current input baud rate and fill a new value */
+        tio.c_cflag &= ~(CBAUD << IBSHIFT);
+        tio.c_cflag |= BOTHER << IBSHIFT;
+        /* When 4th argument is not provided reuse output baud rate */
+        tio.c_ispeed = (argc == 4) ? atoi(argv[3]) : atoi(argv[2]);
+
+        /* Set new serial port settings via supported ioctl */
+#ifdef TCSETS2
+        rc = ioctl(fd, TCSETS2, &tio);
+#else
+        rc = ioctl(fd, TCSETS, &tio);
+#endif
+        if (rc) {
+            perror("TCSETS");
+            close(fd);
+            exit(EXIT_FAILURE);
+        }
+
+        /* And get new values which were really configured */
+#ifdef TCGETS2
+        rc = ioctl(fd, TCGETS2, &tio);
+#else
+        rc = ioctl(fd, TCGETS, &tio);
+#endif
+        if (rc) {
+            perror("TCGETS");
+            close(fd);
+            exit(EXIT_FAILURE);
+        }
+    }
+
+    close(fd);
+
+    printf("output baud rate: %u\en", tio.c_ospeed);
+    printf("input baud rate: %u\en", tio.c_ispeed);
+
+    exit(EXIT_SUCCESS);
+#endif
+}
+.EE
 .SH SEE ALSO
 .BR ldattach (1),
 .BR ioctl (2),
-- 
2.20.1

Re: [PATCH v4] ioctl_tty.2: Add example how to get or set baudrate on the serial port

[Pali Rohár via Libc-alpha]

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

On Tuesday 10 August 2021 21:49:28 Pali Rohár wrote:
> Setting custom baudrate for which is not defined Bnnn constant is possible
> via BOTHER flag and then filling speed in c_ospeed and c_ispeed fields.
> 
> These two fields are either in struct termios or struct termios2. Former
> belongs to TCGETS/TCSETS ioctls, latter to TCGETS2/TCSETS2 ioctls.
> 
> BOTHER flag with these two fields and new struct termios2 is not supported
> by older versions of include header files.
> 
> Some architectures (e.g. amd64) provide both struct termios and struct
> termios2, but c_ospeed and c_ispeed are only in struct termios2.
> 
> Some other architectures (e.g. alpha) provide both struct termios and struct
> termios2 and both have c_ospeed and c_ispeed fields.
> 
> And some other architectures (e.g. powerpc) provide only struct termios
> (no struct termios2) and it has c_ospeed and c_ispeed fields.
> 
> So basically to support all architectures it is needed to use
> struct termios2 when TCGETS2/TCSETS2 is supported. Otherwise it is needed
> to use struct termios with TCGETS/TCSETS (case for e.g. powerpc).
> 
> Setting input baudrate is done via IBSHIFT macro.
> 
> Signed-off-by: Pali Rohár <pali@kernel.org>
> 
> ---
> Changes in v4:
> * Add SPDX-License-Identifier
> * Correctly process split baudrates (separate output and input) via IBSHIFT
> * Update commit message
> 
> Changes in v3:
> * Check support for custom baudrate only based on BOTHER macro
> * Use TCGETS/TCSETS/termios when TCGETS2/TCSETS2/termios2 is not available
> 
> Changes in v2:
> * Use \e for backslash
> * Use exit(EXIT_*) instead of return num
> * Sort includes
> * Add comment about possible fallback
> ---
>  man2/ioctl_tty.2 | 100 +++++++++++++++++++++++++++++++++++++++++++++++
>  1 file changed, 100 insertions(+)
> 
> diff --git a/man2/ioctl_tty.2 b/man2/ioctl_tty.2
> index abfdc1e21fe9..7b2b03ff6757 100644
> --- a/man2/ioctl_tty.2
> +++ b/man2/ioctl_tty.2
> @@ -796,6 +796,106 @@ main(void)
>      close(fd);
>  }
>  .EE
> +.PP
> +Get or set arbitrary baudrate on the serial port.
> +.PP
> +.EX
> +/* SPDX-License-Identifier: GPL-2.0-or-later */
> +
> +#include <asm/termbits.h>
> +#include <fcntl.h>
> +#include <stdio.h>
> +#include <stdlib.h>
> +#include <sys/ioctl.h>
> +#include <sys/types.h>
> +#include <unistd.h>
> +
> +int
> +main(int argc, char *argv[])
> +{
> +#ifndef BOTHER
> +    fprintf(stderr, "BOTHER is unsupported\en");
> +    /* Program may fallback to TCGETS/TCSETS with Bnnn constants */
> +    exit(EXIT_FAILURE);
> +#else
> +    /* Declare tio structure, its type depends on supported ioctl */
> +#ifdef TCGETS2
> +    struct termios2 tio;
> +#else
> +    struct termios tio;
> +#endif
> +    int fd, rc;
> +
> +    if (argc != 2 && argc != 3 && argc != 4) {
> +        fprintf(stderr, "Usage: %s device [output [input] ]\en", argv[0]);
> +        exit(EXIT_FAILURE);
> +    }
> +
> +    fd = open(argv[1], O_RDWR | O_NONBLOCK | O_NOCTTY);
> +    if (fd < 0) {
> +        perror("open");
> +        exit(EXIT_FAILURE);
> +    }
> +
> +    /* Get the current serial port settings via supported ioctl */
> +#ifdef TCGETS2
> +    rc = ioctl(fd, TCGETS2, &tio);
> +#else
> +    rc = ioctl(fd, TCGETS, &tio);
> +#endif
> +    if (rc) {
> +        perror("TCGETS");
> +        close(fd);
> +        exit(EXIT_FAILURE);
> +    }
> +
> +    /* Change baud rate when more arguments were provided */
> +    if (argc == 3 || argc == 4) {
> +        /* Clear the current output baud rate and fill a new value */
> +        tio.c_cflag &= ~CBAUD;
> +        tio.c_cflag |= BOTHER;
> +        tio.c_ospeed = atoi(argv[2]);
> +
> +        /* Clear the current input baud rate and fill a new value */
> +        tio.c_cflag &= ~(CBAUD << IBSHIFT);
> +        tio.c_cflag |= BOTHER << IBSHIFT;
> +        /* When 4th argument is not provided reuse output baud rate */
> +        tio.c_ispeed = (argc == 4) ? atoi(argv[3]) : atoi(argv[2]);
> +
> +        /* Set new serial port settings via supported ioctl */
> +#ifdef TCSETS2
> +        rc = ioctl(fd, TCSETS2, &tio);
> +#else
> +        rc = ioctl(fd, TCSETS, &tio);
> +#endif
> +        if (rc) {
> +            perror("TCSETS");
> +            close(fd);
> +            exit(EXIT_FAILURE);
> +        }
> +
> +        /* And get new values which were really configured */
> +#ifdef TCGETS2
> +        rc = ioctl(fd, TCGETS2, &tio);
> +#else
> +        rc = ioctl(fd, TCGETS, &tio);
> +#endif
> +        if (rc) {
> +            perror("TCGETS");
> +            close(fd);
> +            exit(EXIT_FAILURE);
> +        }
> +    }
> +
> +    close(fd);
> +
> +    printf("output baud rate: %u\en", tio.c_ospeed);
> +    printf("input baud rate: %u\en", tio.c_ispeed);
> +
> +    exit(EXIT_SUCCESS);
> +#endif
> +}
> +.EE
>  .SH SEE ALSO
>  .BR ldattach (1),
>  .BR ioctl (2),
> -- 
> 2.20.1
> 

Alejandro, in case you are interested I wrote also longer version which
can be compiled also with header files without BOTHER support.

I found out that because glibc does not support setting BOTHER speeds,
it also is not able to read current speed (via cfgetospeed()) if serial
port is configured to BOTHER state. And because lot of applications,
including GNU stty, use glibc's cfgetospeed() they are not able to parse
tty serial ports when BOTHER is set.

So due current glibc version, it is preferred to use Bnnn constants and
use BOTHER with c_ospeed only in case when there is no corresponding
Bnnn constant.

In this longer version, this preference is implemented.

But because this longer version is _longer_ I do not know if it is a
good idea to have it in manpage, even it is more preferred for
interoperability with existing applications.

Greg, if you have time, I would like to ask for reviewing new version
of manpage patch (or longer version). Or if you have an idea what is
better example in manpage (short or that longer version).

Longer version is below as MIME inline part of email.

[-- Attachment #2: Type: text/x-csrc, Size: 4880 bytes --]

/* SPDX-FileCopyrightText: 2021 Pali Rohár <pali@kernel.org> */
/* SPDX-License-Identifier: GPL-2.0-or-later */

#include <asm/termbits.h>
#include <fcntl.h>
#include <stdio.h>
#include <stdlib.h>
#include <sys/ioctl.h>
#include <sys/types.h>
#include <unistd.h>

#define B(n) { B##n, n }
static
struct { tcflag_t bn; unsigned int n; }
map[] =
{
    B(0), B(50), B(75), B(110), B(134), B(150), B(200), B(300), B(600),
    B(1200), B(1800), B(2400), B(4800), B(9600), B(19200), B(38400),
    B(57600), B(115200), B(230400), B(460800), B(500000), B(576000),
    B(921600), B(1000000), B(1152000), B(1500000), B(2000000),
#ifdef B2500000
    /* non-SPARC architectures support these Bnnn constants */
    B(2500000), B(3000000), B(3500000), B(4000000)
#else
    /* SPARC architecture supports these Bnnn constants */
    B(76800), B(153600), B(307200), B(614400)
#endif
};
#undef B

static
tcflag_t
map_n_to_bn(unsigned int n)
{
    size_t i;

    for (i = 0; i < sizeof(map)/sizeof(map[0]); i++) {
        if (map[i].n == n)
            return map[i].bn;
    }

    return B0;
}

static
unsigned int
map_bn_to_n(tcflag_t bn)
{
    size_t i;

    for (i = 0; i < sizeof(map)/sizeof(map[0]); i++) {
        if (map[i].bn == bn)
            return map[i].n;
    }

    return 0;
}


int
main(int argc, char *argv[])
{
    /* Declare tio structure, its type depends on supported ioctl */
#ifdef TCGETS2
    struct termios2 tio;
#else
    struct termios tio;
#endif
    unsigned int n;
    tcflag_t bn;
    int fd, rc;

    if (argc != 2 && argc != 3 && argc != 4) {
        fprintf(stderr, "Usage: %s device [output [input] ]\n", argv[0]);
        exit(EXIT_FAILURE);
    }

    fd = open(argv[1], O_RDWR | O_NONBLOCK | O_NOCTTY);
    if (fd < 0) {
        perror("open");
        exit(EXIT_FAILURE);
    }

    /* Get the current serial port settings via supported ioctl */
#ifdef TCGETS2
    rc = ioctl(fd, TCGETS2, &tio);
#else
    rc = ioctl(fd, TCGETS, &tio);
#endif
    if (rc) {
        perror("TCGETS");
        close(fd);
        exit(EXIT_FAILURE);
    }

    /* Change baud rate when more arguments were provided */
    if (argc == 3 || argc == 4) {
        /* Clear the current output baud rate and fill a new value */
        n = atoi(argv[2]);
        /* When possible prefer usage of Bnnn constant as glibc-based
           applications are not able to parse BOTHER c_ospeed baud rate */
        bn = map_n_to_bn(n);
        if (n != 0 && bn == B0) {
#ifdef BOTHER
            bn = BOTHER;
#else
            fprintf(stderr, "baud rate %u is unsupported\n", n);
            close(fd);
            exit(EXIT_FAILURE);
#endif
        }
        tio.c_cflag &= ~CBAUD;
        tio.c_cflag |= bn;
#ifdef BOTHER
        tio.c_ospeed = n;
#endif

        /* When 4th argument is not provided reuse output baud rate */
        if (argc == 4) {
            n = atoi(argv[3]);
            bn = map_n_to_bn(n);
            /* Clear the current input baud rate and fill a new value */
            if (n != 0 && bn == B0) {
#ifdef BOTHER
                bn = BOTHER;
#else
                fprintf(stderr, "baud rate %u is unsupported\n", n);
                close(fd);
                exit(EXIT_FAILURE);
#endif
            }
        }

        if ((tio.c_cflag & CBAUD) != bn) {
#ifdef IBSHIFT
            tio.c_cflag &= ~(CBAUD << IBSHIFT);
            tio.c_cflag |= bn << IBSHIFT;
#ifdef BOTHER
            tio.c_ispeed = n;
#endif
#else
            fprintf(stderr, "split baud rates are unsupported\n", n);
            close(fd);
            exit(EXIT_FAILURE);
#endif
        } else {
#ifdef IBSHIFT
            /* B0 sets the input baud to the output baud rate */
            tio.c_cflag &= ~(CBAUD << IBSHIFT);
            tio.c_cflag |= B0 << IBSHIFT;
#ifdef BOTHER
            tio.c_ispeed = 0;
#endif
#endif
        }

        /* Set new serial port settings via supported ioctl */
#ifdef TCSETS2
        rc = ioctl(fd, TCSETS2, &tio);
#else
        rc = ioctl(fd, TCSETS, &tio);
#endif
        if (rc) {
            perror("TCSETS");
            close(fd);
            exit(EXIT_FAILURE);
        }

        /* And get new values which were really configured */
#ifdef TCGETS2
        rc = ioctl(fd, TCGETS2, &tio);
#else
        rc = ioctl(fd, TCGETS, &tio);
#endif
        if (rc) {
            perror("TCGETS");
            close(fd);
            exit(EXIT_FAILURE);
        }
    }

    bn = tio.c_cflag & CBAUD;
#ifdef BOTHER
    if (bn == BOTHER)
        n = tio.c_ospeed;
    else
#endif
        n = map_bn_to_n(bn);
    printf("output baud rate: %u\n", n);

#ifdef IBSHIFT
    bn = (tio.c_cflag >> IBSHIFT) & CBAUD;
    if (bn == B0)
#endif
        bn = tio.c_cflag & CBAUD;
#ifdef BOTHER
    if (bn == BOTHER)
        n = tio.c_ispeed;
    else
#endif
        n = map_bn_to_n(bn);
    printf("input baud rate: %u\n", n);

    close(fd);
    exit(EXIT_SUCCESS);
}

Re: [PATCH v4] ioctl_tty.2: Add example how to get or set baudrate on the serial port

[Pali Rohár via Libc-alpha]

On Tuesday 10 August 2021 21:49:28 Pali Rohár wrote:
> Setting custom baudrate for which is not defined Bnnn constant is possible
> via BOTHER flag and then filling speed in c_ospeed and c_ispeed fields.
> 
> These two fields are either in struct termios or struct termios2. Former
> belongs to TCGETS/TCSETS ioctls, latter to TCGETS2/TCSETS2 ioctls.
> 
> BOTHER flag with these two fields and new struct termios2 is not supported
> by older versions of include header files.
> 
> Some architectures (e.g. amd64) provide both struct termios and struct
> termios2, but c_ospeed and c_ispeed are only in struct termios2.
> 
> Some other architectures (e.g. alpha) provide both struct termios and struct
> termios2 and both have c_ospeed and c_ispeed fields.
> 
> And some other architectures (e.g. powerpc) provide only struct termios
> (no struct termios2) and it has c_ospeed and c_ispeed fields.
> 
> So basically to support all architectures it is needed to use
> struct termios2 when TCGETS2/TCSETS2 is supported. Otherwise it is needed
> to use struct termios with TCGETS/TCSETS (case for e.g. powerpc).
> 
> Setting input baudrate is done via IBSHIFT macro.
> 
> Signed-off-by: Pali Rohár <pali@kernel.org>

Hello! Do you have any comments on this patch?

> ---
> Changes in v4:
> * Add SPDX-License-Identifier
> * Correctly process split baudrates (separate output and input) via IBSHIFT
> * Update commit message
> 
> Changes in v3:
> * Check support for custom baudrate only based on BOTHER macro
> * Use TCGETS/TCSETS/termios when TCGETS2/TCSETS2/termios2 is not available
> 
> Changes in v2:
> * Use \e for backslash
> * Use exit(EXIT_*) instead of return num
> * Sort includes
> * Add comment about possible fallback
> ---
>  man2/ioctl_tty.2 | 100 +++++++++++++++++++++++++++++++++++++++++++++++
>  1 file changed, 100 insertions(+)
> 
> diff --git a/man2/ioctl_tty.2 b/man2/ioctl_tty.2
> index abfdc1e21fe9..7b2b03ff6757 100644
> --- a/man2/ioctl_tty.2
> +++ b/man2/ioctl_tty.2
> @@ -796,6 +796,106 @@ main(void)
>      close(fd);
>  }
>  .EE
> +.PP
> +Get or set arbitrary baudrate on the serial port.
> +.PP
> +.EX
> +/* SPDX-License-Identifier: GPL-2.0-or-later */
> +
> +#include <asm/termbits.h>
> +#include <fcntl.h>
> +#include <stdio.h>
> +#include <stdlib.h>
> +#include <sys/ioctl.h>
> +#include <sys/types.h>
> +#include <unistd.h>
> +
> +int
> +main(int argc, char *argv[])
> +{
> +#ifndef BOTHER
> +    fprintf(stderr, "BOTHER is unsupported\en");
> +    /* Program may fallback to TCGETS/TCSETS with Bnnn constants */
> +    exit(EXIT_FAILURE);
> +#else
> +    /* Declare tio structure, its type depends on supported ioctl */
> +#ifdef TCGETS2
> +    struct termios2 tio;
> +#else
> +    struct termios tio;
> +#endif
> +    int fd, rc;
> +
> +    if (argc != 2 && argc != 3 && argc != 4) {
> +        fprintf(stderr, "Usage: %s device [output [input] ]\en", argv[0]);
> +        exit(EXIT_FAILURE);
> +    }
> +
> +    fd = open(argv[1], O_RDWR | O_NONBLOCK | O_NOCTTY);
> +    if (fd < 0) {
> +        perror("open");
> +        exit(EXIT_FAILURE);
> +    }
> +
> +    /* Get the current serial port settings via supported ioctl */
> +#ifdef TCGETS2
> +    rc = ioctl(fd, TCGETS2, &tio);
> +#else
> +    rc = ioctl(fd, TCGETS, &tio);
> +#endif
> +    if (rc) {
> +        perror("TCGETS");
> +        close(fd);
> +        exit(EXIT_FAILURE);
> +    }
> +
> +    /* Change baud rate when more arguments were provided */
> +    if (argc == 3 || argc == 4) {
> +        /* Clear the current output baud rate and fill a new value */
> +        tio.c_cflag &= ~CBAUD;
> +        tio.c_cflag |= BOTHER;
> +        tio.c_ospeed = atoi(argv[2]);
> +
> +        /* Clear the current input baud rate and fill a new value */
> +        tio.c_cflag &= ~(CBAUD << IBSHIFT);
> +        tio.c_cflag |= BOTHER << IBSHIFT;
> +        /* When 4th argument is not provided reuse output baud rate */
> +        tio.c_ispeed = (argc == 4) ? atoi(argv[3]) : atoi(argv[2]);
> +
> +        /* Set new serial port settings via supported ioctl */
> +#ifdef TCSETS2
> +        rc = ioctl(fd, TCSETS2, &tio);
> +#else
> +        rc = ioctl(fd, TCSETS, &tio);
> +#endif
> +        if (rc) {
> +            perror("TCSETS");
> +            close(fd);
> +            exit(EXIT_FAILURE);
> +        }
> +
> +        /* And get new values which were really configured */
> +#ifdef TCGETS2
> +        rc = ioctl(fd, TCGETS2, &tio);
> +#else
> +        rc = ioctl(fd, TCGETS, &tio);
> +#endif
> +        if (rc) {
> +            perror("TCGETS");
> +            close(fd);
> +            exit(EXIT_FAILURE);
> +        }
> +    }
> +
> +    close(fd);
> +
> +    printf("output baud rate: %u\en", tio.c_ospeed);
> +    printf("input baud rate: %u\en", tio.c_ispeed);
> +
> +    exit(EXIT_SUCCESS);
> +#endif
> +}
> +.EE
>  .SH SEE ALSO
>  .BR ldattach (1),
>  .BR ioctl (2),
> -- 
> 2.20.1
> 

Re: [PATCH v4] ioctl_tty.2: Add example how to get or set baudrate on the serial port

[Alejandro Colomar (man-pages) via Libc-alpha]

Hi, Pali!

On 8/31/21 10:34 PM, Pali Rohár wrote:
> On Tuesday 10 August 2021 21:49:28 Pali Rohár wrote:
>> Setting custom baudrate for which is not defined Bnnn constant is possible
>> via BOTHER flag and then filling speed in c_ospeed and c_ispeed fields.
>>
>> These two fields are either in struct termios or struct termios2. Former
>> belongs to TCGETS/TCSETS ioctls, latter to TCGETS2/TCSETS2 ioctls.
>>
>> BOTHER flag with these two fields and new struct termios2 is not supported
>> by older versions of include header files.
>>
>> Some architectures (e.g. amd64) provide both struct termios and struct
>> termios2, but c_ospeed and c_ispeed are only in struct termios2.
>>
>> Some other architectures (e.g. alpha) provide both struct termios and struct
>> termios2 and both have c_ospeed and c_ispeed fields.
>>
>> And some other architectures (e.g. powerpc) provide only struct termios
>> (no struct termios2) and it has c_ospeed and c_ispeed fields.
>>
>> So basically to support all architectures it is needed to use
>> struct termios2 when TCGETS2/TCSETS2 is supported. Otherwise it is needed
>> to use struct termios with TCGETS/TCSETS (case for e.g. powerpc).
>>
>> Setting input baudrate is done via IBSHIFT macro.
>>
>> Signed-off-by: Pali Rohár <pali@kernel.org>
> 
> Hello! Do you have any comments on this patch?

Sorry, I started to fix the licensing issues Greg pointed out, and 
forgot about this.

I assume it's good since you have been doing a lot of related work in 
recent patches.  I'll only point out a cosmetic issue with the 
preprocessor stuff:  I'd indent with a single space after '#' to clarify 
preprocessor #if #else #endif relationships and improve readability.  I 
also prefer '#if [!]defined()' rather than '#if[n]def' (except for 
include guards); and there seems to be a mix in the existing pages, so 
I'll standardize that way from now on.

For example:

#if !defined a
#else
# if defined b
# endif
#endif

However, I applied those changes myself in a following patch, so you 
don't worry about them.

Patch applied!

Thanks,

Alex

> 
>> ---
>> Changes in v4:
>> * Add SPDX-License-Identifier
>> * Correctly process split baudrates (separate output and input) via IBSHIFT
>> * Update commit message
>>
>> Changes in v3:
>> * Check support for custom baudrate only based on BOTHER macro
>> * Use TCGETS/TCSETS/termios when TCGETS2/TCSETS2/termios2 is not available
>>
>> Changes in v2:
>> * Use \e for backslash
>> * Use exit(EXIT_*) instead of return num
>> * Sort includes
>> * Add comment about possible fallback
>> ---
>>   man2/ioctl_tty.2 | 100 +++++++++++++++++++++++++++++++++++++++++++++++
>>   1 file changed, 100 insertions(+)
>>
>> diff --git a/man2/ioctl_tty.2 b/man2/ioctl_tty.2
>> index abfdc1e21fe9..7b2b03ff6757 100644
>> --- a/man2/ioctl_tty.2
>> +++ b/man2/ioctl_tty.2
>> @@ -796,6 +796,106 @@ main(void)
>>       close(fd);
>>   }
>>   .EE
>> +.PP
>> +Get or set arbitrary baudrate on the serial port.
>> +.PP
>> +.EX
>> +/* SPDX-License-Identifier: GPL-2.0-or-later */
>> +
>> +#include <asm/termbits.h>
>> +#include <fcntl.h>
>> +#include <stdio.h>
>> +#include <stdlib.h>
>> +#include <sys/ioctl.h>
>> +#include <sys/types.h>
>> +#include <unistd.h>
>> +
>> +int
>> +main(int argc, char *argv[])
>> +{
>> +#ifndef BOTHER
>> +    fprintf(stderr, "BOTHER is unsupported\en");
>> +    /* Program may fallback to TCGETS/TCSETS with Bnnn constants */
>> +    exit(EXIT_FAILURE);
>> +#else
>> +    /* Declare tio structure, its type depends on supported ioctl */
>> +#ifdef TCGETS2
>> +    struct termios2 tio;
>> +#else
>> +    struct termios tio;
>> +#endif
>> +    int fd, rc;
>> +
>> +    if (argc != 2 && argc != 3 && argc != 4) {
>> +        fprintf(stderr, "Usage: %s device [output [input] ]\en", argv[0]);
>> +        exit(EXIT_FAILURE);
>> +    }
>> +
>> +    fd = open(argv[1], O_RDWR | O_NONBLOCK | O_NOCTTY);
>> +    if (fd < 0) {
>> +        perror("open");
>> +        exit(EXIT_FAILURE);
>> +    }
>> +
>> +    /* Get the current serial port settings via supported ioctl */
>> +#ifdef TCGETS2
>> +    rc = ioctl(fd, TCGETS2, &tio);
>> +#else
>> +    rc = ioctl(fd, TCGETS, &tio);
>> +#endif
>> +    if (rc) {
>> +        perror("TCGETS");
>> +        close(fd);
>> +        exit(EXIT_FAILURE);
>> +    }
>> +
>> +    /* Change baud rate when more arguments were provided */
>> +    if (argc == 3 || argc == 4) {
>> +        /* Clear the current output baud rate and fill a new value */
>> +        tio.c_cflag &= ~CBAUD;
>> +        tio.c_cflag |= BOTHER;
>> +        tio.c_ospeed = atoi(argv[2]);
>> +
>> +        /* Clear the current input baud rate and fill a new value */
>> +        tio.c_cflag &= ~(CBAUD << IBSHIFT);
>> +        tio.c_cflag |= BOTHER << IBSHIFT;
>> +        /* When 4th argument is not provided reuse output baud rate */
>> +        tio.c_ispeed = (argc == 4) ? atoi(argv[3]) : atoi(argv[2]);
>> +
>> +        /* Set new serial port settings via supported ioctl */
>> +#ifdef TCSETS2
>> +        rc = ioctl(fd, TCSETS2, &tio);
>> +#else
>> +        rc = ioctl(fd, TCSETS, &tio);
>> +#endif
>> +        if (rc) {
>> +            perror("TCSETS");
>> +            close(fd);
>> +            exit(EXIT_FAILURE);
>> +        }
>> +
>> +        /* And get new values which were really configured */
>> +#ifdef TCGETS2
>> +        rc = ioctl(fd, TCGETS2, &tio);
>> +#else
>> +        rc = ioctl(fd, TCGETS, &tio);
>> +#endif
>> +        if (rc) {
>> +            perror("TCGETS");
>> +            close(fd);
>> +            exit(EXIT_FAILURE);
>> +        }
>> +    }
>> +
>> +    close(fd);
>> +
>> +    printf("output baud rate: %u\en", tio.c_ospeed);
>> +    printf("input baud rate: %u\en", tio.c_ispeed);
>> +
>> +    exit(EXIT_SUCCESS);
>> +#endif
>> +}
>> +.EE
>>   .SH SEE ALSO
>>   .BR ldattach (1),
>>   .BR ioctl (2),
>> -- 
>> 2.20.1
>>


-- 
Alejandro Colomar
Linux man-pages comaintainer; https://www.kernel.org/doc/man-pages/
http://www.alejandro-colomar.es/

Re: [PATCH v4] ioctl_tty.2: Add example how to get or set baudrate on the serial port

[Pali Rohár via Libc-alpha]

On Friday 10 September 2021 15:37:54 Alejandro Colomar (man-pages) wrote:
> Hi, Pali!
> 
> On 8/31/21 10:34 PM, Pali Rohár wrote:
> > On Tuesday 10 August 2021 21:49:28 Pali Rohár wrote:
> > > Setting custom baudrate for which is not defined Bnnn constant is possible
> > > via BOTHER flag and then filling speed in c_ospeed and c_ispeed fields.
> > > 
> > > These two fields are either in struct termios or struct termios2. Former
> > > belongs to TCGETS/TCSETS ioctls, latter to TCGETS2/TCSETS2 ioctls.
> > > 
> > > BOTHER flag with these two fields and new struct termios2 is not supported
> > > by older versions of include header files.
> > > 
> > > Some architectures (e.g. amd64) provide both struct termios and struct
> > > termios2, but c_ospeed and c_ispeed are only in struct termios2.
> > > 
> > > Some other architectures (e.g. alpha) provide both struct termios and struct
> > > termios2 and both have c_ospeed and c_ispeed fields.
> > > 
> > > And some other architectures (e.g. powerpc) provide only struct termios
> > > (no struct termios2) and it has c_ospeed and c_ispeed fields.
> > > 
> > > So basically to support all architectures it is needed to use
> > > struct termios2 when TCGETS2/TCSETS2 is supported. Otherwise it is needed
> > > to use struct termios with TCGETS/TCSETS (case for e.g. powerpc).
> > > 
> > > Setting input baudrate is done via IBSHIFT macro.
> > > 
> > > Signed-off-by: Pali Rohár <pali@kernel.org>
> > 
> > Hello! Do you have any comments on this patch?
> 
> Sorry, I started to fix the licensing issues Greg pointed out, and forgot
> about this.
> 
> I assume it's good since you have been doing a lot of related work in recent
> patches.  I'll only point out a cosmetic issue with the preprocessor stuff:
> I'd indent with a single space after '#' to clarify preprocessor #if #else
> #endif relationships and improve readability.  I also prefer '#if
> [!]defined()' rather than '#if[n]def' (except for include guards); and there
> seems to be a mix in the existing pages, so I'll standardize that way from
> now on.
> 
> For example:
> 
> #if !defined a
> #else
> # if defined b
> # endif
> #endif
> 
> However, I applied those changes myself in a following patch, so you don't
> worry about them.

Ok, perfect, thanks!

> Patch applied!
> 
> Thanks,
> 
> Alex