[PATCH] please document if ENOTSUP == EOPNOTSUPP

classic Classic list List threaded Threaded
4 messages Options
Reply | Threaded
Open this post in threaded view
|

[PATCH] please document if ENOTSUP == EOPNOTSUPP

Nicolas Boulenguez
Hello.

Please document the difference between these error codes in the libc
documentation.

I am posting on this list because I have been told to do so at
https://sourceware.org/bugzilla/show_bug.cgi?id=2363

The patch below is also available there as attachment 11383.

Thanks.

Description: Document that EOPNOTSUPP and ENOTSUP are equal, not distinct
Bug-Debian: https://bugs.debian.org/337013
Forwarded: https://sourceware.org/bugzilla/show_bug.cgi?id=2363
Author: Nicolas Boulenguez <[hidden email]>
Author: Florian Weimer <[hidden email]>

--- a/manual/errno.texi
+++ b/manual/errno.texi
@@ -84,11 +84,18 @@
 reserved names.  @xref{Reserved Names}.
 
 The error code values are all positive integers and are all distinct,
-with one exception: @code{EWOULDBLOCK} and @code{EAGAIN} are the same.
-Since the values are distinct, you can use them as labels in a
-@code{switch} statement; just don't use both @code{EWOULDBLOCK} and
-@code{EAGAIN}.  Your program should not make any other assumptions about
+so they can be used as labels in a @code{switch} statement.
+Your program should not make any other assumptions about
 the specific values of these symbolic constants.
+Moreover, @theglibc{} does two exceptions:
+@itemize @bullet
+@item The values of @code{AGAIN} and @code{EWOULDBLOCK} are the
+same on every supported operating system.
+@item The values of @code{ENOTSUP} and @code{EOPNOTSUPP} are equal
+on some supported operating systems, for example GNU/Linux.
+@end itemize
+To make your program portable, you should check for both codes and
+treat them the same.
 
 The value of @code{errno} doesn't necessarily have to correspond to any
 of these macros, since some library functions might return other error
@@ -383,8 +390,7 @@
 @standards{POSIX.1, errno.h}
 @errno{EAGAIN, 35, Resource temporarily unavailable}
 The call might work if you try again
-later.  The macro @code{EWOULDBLOCK} is another name for @code{EAGAIN};
-they are always the same in @theglibc{}.
+later.
 
 This error can happen in a few different situations:
 
@@ -395,12 +401,6 @@
 until some external condition makes it possible to read, write, or
 connect (whatever the operation).  You can use @code{select} to find out
 when the operation will be possible; @pxref{Waiting for I/O}.
-
-@strong{Portability Note:} In many older Unix systems, this condition
-was indicated by @code{EWOULDBLOCK}, which was a distinct error code
-different from @code{EAGAIN}.  To make your program portable, you should
-check for both codes and treat them the same.
-
 @item
 A temporary resource shortage made an operation impossible.  @code{fork}
 can return this error.  It indicates that the shortage is expected to
@@ -411,16 +411,16 @@
 so usually an interactive program should report the error to the user
 and return to its command loop.
 @end itemize
+
+@strong{Portability Note:} In @theglibc{},
+@code{EAGAIN} and @code{EWOULDBLOCK} are equal.
+Portable code should check for both errors and treat them the same.
 @end deftypevr
 
 @deftypevr Macro int EWOULDBLOCK
 @standards{BSD, errno.h}
 @errno{EWOULDBLOCK, EAGAIN, Operation would block}
 In @theglibc{}, this is another name for @code{EAGAIN} (above).
-The values are always the same, on every operating system.
-
-C libraries in many older Unix systems have @code{EWOULDBLOCK} as a
-separate error code.
 @end deftypevr
 
 @deftypevr Macro int EINPROGRESS
@@ -492,6 +492,10 @@
 error can happen for many calls when the object does not support the
 particular operation; it is a generic indication that the server knows
 nothing to do for that call.
+
+@strong{Portability Note:} Depending on the operating system, the
+@code{EOPNOTSUPP} and @code{ENOTSUP} macros may have the same value.
+Portable code should check for both errors and treat them the same.
 @end deftypevr
 
 @deftypevr Macro int EPFNOSUPPORT
@@ -764,6 +768,10 @@
 
 If the entire function is not available at all in the implementation,
 it returns @code{ENOSYS} instead.
+
+@strong{Portability Note:} Depending on the operating system, the
+@code{EOPNOTSUPP} and @code{ENOTSUP} macros may have the same value.
+Portable code should check for both errors and treat them the same.
 @end deftypevr
 
 @deftypevr Macro int EILSEQ
Reply | Threaded
Open this post in threaded view
|

Re: [PATCH] please document if ENOTSUP == EOPNOTSUPP

Carlos O'Donell-6
On 8/21/19 11:06 AM, Nicolas Boulenguez wrote:

> Hello.
>
> Please document the difference between these error codes in the libc
> documentation.
>
> I am posting on this list because I have been told to do so at
> https://sourceware.org/bugzilla/show_bug.cgi?id=2363
>
> The patch below is also available there as attachment 11383.
>
> Thanks.
>
> Description: Document that EOPNOTSUPP and ENOTSUP are equal, not distinct
> Bug-Debian: https://bugs.debian.org/337013
> Forwarded: https://sourceware.org/bugzilla/show_bug.cgi?id=2363
> Author: Nicolas Boulenguez <[hidden email]>
> Author: Florian Weimer <[hidden email]>

Florian,

Are you part-author of these changes?

This looks OK to me with the suggestions accepted.

Please post a v2.

>
> --- a/manual/errno.texi
> +++ b/manual/errno.texi
> @@ -84,11 +84,18 @@
>  reserved names.  @xref{Reserved Names}.
>  
>  The error code values are all positive integers and are all distinct,
> -with one exception: @code{EWOULDBLOCK} and @code{EAGAIN} are the same.
> -Since the values are distinct, you can use them as labels in a
> -@code{switch} statement; just don't use both @code{EWOULDBLOCK} and
> -@code{EAGAIN}.  Your program should not make any other assumptions about
> +so they can be used as labels in a @code{switch} statement.
> +Your program should not make any other assumptions about
>  the specific values of these symbolic constants.
> +Moreover, @theglibc{} does two exceptions:

Suggest:
There are two exceptions to this rule:

> +@itemize @bullet
> +@item The values of @code{AGAIN} and @code{EWOULDBLOCK} are the

s/AGAIN/EAGAIN/g

s/the same/equal/g

> +same on every supported operating system.
> +@item The values of @code{ENOTSUP} and @code{EOPNOTSUPP} are equal
> +on some supported operating systems, for example GNU/Linux.
> +@end itemize
> +To make your program portable, you should check for both codes and
> +treat them the same.

OK.

>  
>  The value of @code{errno} doesn't necessarily have to correspond to any
>  of these macros, since some library functions might return other error
> @@ -383,8 +390,7 @@
>  @standards{POSIX.1, errno.h}
>  @errno{EAGAIN, 35, Resource temporarily unavailable}
>  The call might work if you try again
> -later.  The macro @code{EWOULDBLOCK} is another name for @code{EAGAIN};
> -they are always the same in @theglibc{}.
> +later.

OK.

>  
>  This error can happen in a few different situations:
>  
> @@ -395,12 +401,6 @@
>  until some external condition makes it possible to read, write, or
>  connect (whatever the operation).  You can use @code{select} to find out
>  when the operation will be possible; @pxref{Waiting for I/O}.
> -
> -@strong{Portability Note:} In many older Unix systems, this condition
> -was indicated by @code{EWOULDBLOCK}, which was a distinct error code
> -different from @code{EAGAIN}.  To make your program portable, you should
> -check for both codes and treat them the same.

OK.

> -
>  @item
>  A temporary resource shortage made an operation impossible.  @code{fork}
>  can return this error.  It indicates that the shortage is expected to
> @@ -411,16 +411,16 @@
>  so usually an interactive program should report the error to the user
>  and return to its command loop.
>  @end itemize
> +
> +@strong{Portability Note:} In @theglibc{},
> +@code{EAGAIN} and @code{EWOULDBLOCK} are equal.
> +Portable code should check for both errors and treat them the same.

OK.

>  @end deftypevr
>  
>  @deftypevr Macro int EWOULDBLOCK
>  @standards{BSD, errno.h}
>  @errno{EWOULDBLOCK, EAGAIN, Operation would block}
>  In @theglibc{}, this is another name for @code{EAGAIN} (above).
> -The values are always the same, on every operating system.
> -
> -C libraries in many older Unix systems have @code{EWOULDBLOCK} as a
> -separate error code.

OK.

>  @end deftypevr
>  
>  @deftypevr Macro int EINPROGRESS
> @@ -492,6 +492,10 @@
>  error can happen for many calls when the object does not support the
>  particular operation; it is a generic indication that the server knows
>  nothing to do for that call.
> +
> +@strong{Portability Note:} Depending on the operating system, the
> +@code{EOPNOTSUPP} and @code{ENOTSUP} macros may have the same value.
> +Portable code should check for both errors and treat them the same.

OK.

>  @end deftypevr
>  
>  @deftypevr Macro int EPFNOSUPPORT
> @@ -764,6 +768,10 @@
>  
>  If the entire function is not available at all in the implementation,
>  it returns @code{ENOSYS} instead.
> +
> +@strong{Portability Note:} Depending on the operating system, the
> +@code{EOPNOTSUPP} and @code{ENOTSUP} macros may have the same value.
> +Portable code should check for both errors and treat them the same.

OK.

>  @end deftypevr
>  
>  @deftypevr Macro int EILSEQ
>


--
Cheers,
Carlos.
Reply | Threaded
Open this post in threaded view
|

Re: [PATCH] please document if ENOTSUP == EOPNOTSUPP

Nicolas Boulenguez
> > Author: Florian Weimer <[hidden email]>
> Florian,
> Are you part-author of these changes?

In case he does not remember, I have added Florian because of the
corrections he suggested in comment 6.

> Please post a v2.

The new patch is available at
https://sourceware.org/bugzilla/attachment.cgi as attachment 11962.

Here are the changes:

--- a/manual_same_errno.diff
+++ b/manual_same_errno.diff
@@ -3,6 +3,7 @@
 Forwarded: https://sourceware.org/bugzilla/show_bug.cgi?id=2363
 Author: Nicolas Boulenguez <[hidden email]>
 Author: Florian Weimer <[hidden email]>
+Author: Carlos O'Donell <[hidden email]>
 
 --- a/manual/errno.texi
 +++ b/manual/errno.texi
@@ -17,10 +18,10 @@
 +so they can be used as labels in a @code{switch} statement.
 +Your program should not make any other assumptions about
  the specific values of these symbolic constants.
-+Moreover, @theglibc{} does two exceptions:
++There are two exceptions to this rule:
 +@itemize @bullet
-+@item The values of @code{AGAIN} and @code{EWOULDBLOCK} are the
-+same on every supported operating system.
++@item The values of @code{EAGAIN} and @code{EWOULDBLOCK} are
++equal on every supported operating system.
 +@item The values of @code{ENOTSUP} and @code{EOPNOTSUPP} are equal
 +on some supported operating systems, for example GNU/Linux.
 +@end itemize
@@ -79,7 +80,7 @@
  nothing to do for that call.
 +
 +@strong{Portability Note:} Depending on the operating system, the
-+@code{EOPNOTSUPP} and @code{ENOTSUP} macros may have the same value.
++values of @code{EOPNOTSUPP} and @code{ENOTSUP} may be equal.
 +Portable code should check for both errors and treat them the same.
  @end deftypevr
 
@@ -90,7 +91,7 @@
  it returns @code{ENOSYS} instead.
 +
 +@strong{Portability Note:} Depending on the operating system, the
-+@code{EOPNOTSUPP} and @code{ENOTSUP} macros may have the same value.
++values of @code{EOPNOTSUPP} and @code{ENOTSUP} may be equal.
 +Portable code should check for both errors and treat them the same.
  @end deftypevr
 
Reply | Threaded
Open this post in threaded view
|

Re: [PATCH] please document if ENOTSUP == EOPNOTSUPP

Florian Weimer-5
In reply to this post by Carlos O'Donell-6
* Carlos O'Donell:

> Are you part-author of these changes?

I don't think so, I just made a comment in passing.

Thanks,
Florian