Message ID | 20190821150658.GA32668@nicolasthinkpad |
---|---|
State | New |
Headers | show |
Series | please document if ENOTSUP == EOPNOTSUPP | expand |
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 <nicolas@debian.org> > Author: Florian Weimer <fweimer@redhat.com> 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 >
> > Author: Florian Weimer <fweimer@redhat.com> > 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 <nicolas@debian.org> Author: Florian Weimer <fweimer@redhat.com> +Author: Carlos O'Donell <carlos@redhat.com> --- 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
* Carlos O'Donell:
> Are you part-author of these changes?
I don't think so, I just made a comment in passing.
Thanks,
Florian
--- 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