From patchwork Wed Aug 21 15:06:58 2019 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Nicolas Boulenguez X-Patchwork-Id: 1150912 Return-Path: X-Original-To: incoming@patchwork.ozlabs.org Delivered-To: patchwork-incoming@bilbo.ozlabs.org Authentication-Results: ozlabs.org; spf=pass (mailfrom) smtp.mailfrom=sourceware.org (client-ip=209.132.180.131; helo=sourceware.org; envelope-from=libc-alpha-return-104650-incoming=patchwork.ozlabs.org@sourceware.org; receiver=) Authentication-Results: ozlabs.org; dmarc=none (p=none dis=none) header.from=debian.org Authentication-Results: ozlabs.org; dkim=pass (1024-bit key; secure) header.d=sourceware.org header.i=@sourceware.org header.b="pq3YPLuO"; dkim-atps=neutral Received: from sourceware.org (server1.sourceware.org [209.132.180.131]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by ozlabs.org (Postfix) with ESMTPS id 46D9xV2nKyz9sBF for ; Thu, 22 Aug 2019 01:07:09 +1000 (AEST) DomainKey-Signature: a=rsa-sha1; c=nofws; d=sourceware.org; h=list-id :list-unsubscribe:list-subscribe:list-archive:list-post :list-help:sender:date:from:to:subject:message-id:mime-version :content-type; q=dns; s=default; b=f2w+slu+QxdPtLD/LlDsmItm8ssWE 7ioz4odGbYiqzfEH8ORZ5T1WSUuBi67lWBzv4xEdwMJ7ng5UtO43Q7RrvfP4O7/8 +B/j+ix9uqW7qyhSn33VXGWOE3MHmOZe5w4Asa79aI88a3zcgld4R7IOt2q1UJ7P YUzyX8UlPQJjBs= DKIM-Signature: v=1; a=rsa-sha1; c=relaxed; d=sourceware.org; h=list-id :list-unsubscribe:list-subscribe:list-archive:list-post :list-help:sender:date:from:to:subject:message-id:mime-version :content-type; s=default; bh=vHf44uZHzjqBytwx1GY/vVZCnEI=; b=pq3 YPLuOg+nbbM94jWoTa27P+61PjnZR5XuQERf7F/lHpYhOl9p9OwlwotDb7RlhvzZ o54w4zCM3xqKO1CVFDRFmosDC7iBGhsBWzqougEOrl3TEy2+cx2gxXZVjNJlEwtR 0boFyeU0CIjUq/HwtAkAUiuc6Nqli3Wc8/ZSBVKw= Received: (qmail 94539 invoked by alias); 21 Aug 2019 15:07:04 -0000 Mailing-List: contact libc-alpha-help@sourceware.org; run by ezmlm Precedence: bulk List-Id: List-Unsubscribe: List-Subscribe: List-Archive: List-Post: List-Help: , Sender: libc-alpha-owner@sourceware.org Delivered-To: mailing list libc-alpha@sourceware.org Received: (qmail 94511 invoked by uid 89); 21 Aug 2019 15:07:04 -0000 Authentication-Results: sourceware.org; auth=none X-Spam-SWARE-Status: No, score=-12.6 required=5.0 tests=BAYES_00, FREEMAIL_FROM, GIT_PATCH_2, GIT_PATCH_3, RCVD_IN_DNSWL_LOW autolearn=ham version=3.3.1 spammy=moreover, BSD, interactive, shortage X-HELO: smtp6-g21.free.fr Date: Wed, 21 Aug 2019 17:06:58 +0200 From: Nicolas Boulenguez To: libc-alpha@sourceware.org Subject: [PATCH] please document if ENOTSUP == EOPNOTSUPP Message-ID: <20190821150658.GA32668@nicolasthinkpad> MIME-Version: 1.0 Content-Disposition: inline User-Agent: Mutt/1.10.1 (2018-07-13) 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 Author: Florian Weimer --- 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