diff mbox series

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

Message ID 20210730095333.6118-1-pali@kernel.org
State Superseded
Headers show
Series ioctl_tty.2: Add example how to get or set baudrate on the serial port | expand

Checks

Context Check Description
dj/TryBot-apply_patch fail Patch failed to apply to master at the time it was sent

Commit Message

Pali Rohár July 30, 2021, 9:53 a.m. UTC
Signed-off-by: Pali Rohár <pali@kernel.org>
---
 man2/ioctl_tty.2 | 60 ++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 60 insertions(+)

Comments

Alejandro Colomar \(man-pages\) July 30, 2021, 11:47 a.m. UTC | #1
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),
>
Pali Rohár July 30, 2021, 12:05 p.m. UTC | #2
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/
Alejandro Colomar \(man-pages\) July 30, 2021, 12:21 p.m. UTC | #3
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
diff mbox series

Patch

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