cfsetispeed and zero baudrate

cfsetispeed and zero baudrate

[Pali Rohár]

Hello Alejandro!

Currently in cfsetispeed() documentation is written:

  If the input baud rate is set to zero, the input baud rate will be
  equal to the output baud rate.

There is B0 constant which represents "zero baud rate". And also
information that argument for cfsetispeed() (and also cfsetospeed())
must be Bnnn constant.

But above quote documents special handling, "zero" here is really
integer 0 and not pre-defined constant B0.

I think that phrase "If the input baud rate is set to zero" could be
confusing, as based on requirement to use Bnnn constants somebody could
interpret that "zero" as B0.

What do you think, should be above documentation part extended to
express that "zero" is really integer 0 and not constant B0?

Some references:
* glibc really checks for integer 0:
  https://sourceware.org/git/?p=glibc.git;a=blob;f=sysdeps/unix/sysv/linux/speed.c;h=daac5ecde1f3695b8cb178002e8756895406087b;hb=HEAD#l86
* POSIX describes that it is integer 0:
  https://pubs.opengroup.org/onlinepubs/9699919799/functions/tcsetattr.html

Re: cfsetispeed and zero baudrate

[Alejandro Colomar (man-pages)]

Hello Pali!

On 8/30/21 12:38 PM, Pali Rohár wrote:
> Hello Alejandro!
> 
> Currently in cfsetispeed() documentation is written:
> 
>   If the input baud rate is set to zero, the input baud rate will be
>   equal to the output baud rate.
> 
> There is B0 constant which represents "zero baud rate". And also
> information that argument for cfsetispeed() (and also cfsetospeed())
> must be Bnnn constant.
> 
> But above quote documents special handling, "zero" here is really
> integer 0 and not pre-defined constant B0.
> 
> I think that phrase "If the input baud rate is set to zero" could be
> confusing, as based on requirement to use Bnnn constants somebody could
> interpret that "zero" as B0.
> 
> What do you think, should be above documentation part extended to
> express that "zero" is really integer 0 and not constant B0?
> 
> Some references:
> * glibc really checks for integer 0:
>   https://sourceware.org/git/?p=glibc.git;a=blob;f=sysdeps/unix/sysv/linux/speed.c;h=daac5ecde1f3695b8cb178002e8756895406087b;hb=HEAD#l86
> * POSIX describes that it is integer 0:
>   https://pubs.opengroup.org/onlinepubs/9699919799/functions/tcsetattr.html

I think we should, as POSIX does, use literal `0` (and not mention
'zero' at all) to clearly differentiate it from the 'zero baud rate' B0.

Would you send a patch?

Thanks!

Alex

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

[PATCH] termios.3: Clarify zero argument for cfsetispeed()

[Pali Rohár]

Zero in this case refers to literal constant 0 and not symbolic constant B0.

Signed-off-by: Pali Rohár <pali@kernel.org>
---
 man3/termios.3 | 6 +++++-
 1 file changed, 5 insertions(+), 1 deletion(-)

diff --git a/man3/termios.3 b/man3/termios.3
index c96a5c15ec87..f888c15d754c 100644
--- a/man3/termios.3
+++ b/man3/termios.3
@@ -1017,7 +1017,11 @@ which must be specified as one of the
 .BI B nnn
 constants listed above for
 .BR cfsetospeed ().
-If the input baud rate is set to zero, the input baud rate will be
+If the input baud rate is set to literal constant
+.B 0
+(not the symbolic constant
+.BR B0 ),
+the input baud rate will be
 equal to the output baud rate.
 .PP
 .BR cfsetspeed ()
-- 
2.20.1

Re: [PATCH] termios.3: Clarify zero argument for cfsetispeed()

[Michael Kerrisk (man-pages)]

Hello Pali,

On 8/30/21 1:25 PM, Pali Rohár wrote:
> Zero in this case refers to literal constant 0 and not symbolic constant B0.
> 
> Signed-off-by: Pali Rohár <pali@kernel.org>

Thanks. Patch applied.

Cheers,

Michael


> ---
>  man3/termios.3 | 6 +++++-
>  1 file changed, 5 insertions(+), 1 deletion(-)
> 
> diff --git a/man3/termios.3 b/man3/termios.3
> index c96a5c15ec87..f888c15d754c 100644
> --- a/man3/termios.3
> +++ b/man3/termios.3
> @@ -1017,7 +1017,11 @@ which must be specified as one of the
>  .BI B nnn
>  constants listed above for
>  .BR cfsetospeed ().
> -If the input baud rate is set to zero, the input baud rate will be
> +If the input baud rate is set to literal constant
> +.B 0
> +(not the symbolic constant
> +.BR B0 ),
> +the input baud rate will be
>  equal to the output baud rate.
>  .PP
>  .BR cfsetspeed ()
> 


-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/