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

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

[Pali Rohár]

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

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]

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]

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]

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]

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]

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

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]

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

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]

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

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]

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/