Message ID | 20201002151419.32053-2-colomar.6.4.3@gmail.com |
---|---|
State | Not applicable |
Headers |
Return-Path: <libc-alpha-bounces@sourceware.org> X-Original-To: patchwork@sourceware.org Delivered-To: patchwork@sourceware.org Received: from server2.sourceware.org (localhost [IPv6:::1]) by sourceware.org (Postfix) with ESMTP id D6FA8398E41B; Fri, 2 Oct 2020 15:14:53 +0000 (GMT) DKIM-Filter: OpenDKIM Filter v2.11.0 sourceware.org D6FA8398E41B DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=sourceware.org; s=default; t=1601651693; bh=1jz81GvCHHwbiMMhfLuqkJObGuZK1aqG9396huA5nlY=; h=To:Subject:Date:In-Reply-To:References:List-Id:List-Unsubscribe: List-Archive:List-Post:List-Help:List-Subscribe:From:Reply-To:Cc: From; b=jXlXmBKBjio5cyAo9jm215DA3XxyH9BbtTugRWMThKi3fB2uIEyRjJE6xuApp4xFJ dRzToXdKUnrMIaVYjWJXuRnSlAddWdBTieMYiSGCPXlTRQqxkHWRdZnZ39RAHm29VC 6dImCo7t6X47bFqOjqi3q9uuyKHll2Xaza8G6tUw= X-Original-To: libc-alpha@sourceware.org Delivered-To: libc-alpha@sourceware.org Received: from mail-wr1-x443.google.com (mail-wr1-x443.google.com [IPv6:2a00:1450:4864:20::443]) by sourceware.org (Postfix) with ESMTPS id C70A13985429 for <libc-alpha@sourceware.org>; Fri, 2 Oct 2020 15:14:50 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.3.2 sourceware.org C70A13985429 Received: by mail-wr1-x443.google.com with SMTP id s12so2212421wrw.11 for <libc-alpha@sourceware.org>; Fri, 02 Oct 2020 08:14:50 -0700 (PDT) X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references:mime-version:content-transfer-encoding; bh=1jz81GvCHHwbiMMhfLuqkJObGuZK1aqG9396huA5nlY=; b=cPK6BFZBQYZT+3hsSJ+5aUU9oTAiN4MDOhunZj8ESJnEepmSK3PBvRfD06mNVtE1iy 26Do+0MUpLQMFtjhMcOHjFYZBpdJNWz15tJSsSmEKhy/xtgHIFXnAicQv7PhovMp/+XM QDXz8eq1sS6o65xJNYjP+Nw+RHIjrBPgTMVMI8AsKPXk/gjcIoXK5G42zSXRzCUpizxu c6MMBImhCB27hjXxmyM7qRT3mAdMO3SJEXhswOFKeZC4v0yw184Q3JZfUQbev2ODNJDB z39lV7lfEaw7g2WG0WAWkzJh3fWC86lcZB+fDaUa2ZMZzA/DJVj1ZZ1zoFW51/JZ74Bv o7Ug== X-Gm-Message-State: AOAM531l6HPbNj0addirIPZZoI3W6qR4ZXtKLPQSHcsGYERcuf8/Pcbt c7zThaD4bZxcHKQAUoPFGvU= X-Google-Smtp-Source: ABdhPJyEx488CgFMS1kE6MbtP8n7ZQdmrSdRx7HTo+RCeysVRKz2EFPvtGPYCzAEb7QOzua2YRJJrw== X-Received: by 2002:adf:e481:: with SMTP id i1mr3621038wrm.391.1601651689820; Fri, 02 Oct 2020 08:14:49 -0700 (PDT) Received: from localhost.localdomain ([170.253.60.68]) by smtp.googlemail.com with ESMTPSA id u127sm2312237wmu.48.2020.10.02.08.14.48 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Fri, 02 Oct 2020 08:14:49 -0700 (PDT) To: mtk.manpages@gmail.com Subject: [PATCH v4 1/2] system_data_types.7: Add 'void *' Date: Fri, 2 Oct 2020 17:14:19 +0200 Message-Id: <20201002151419.32053-2-colomar.6.4.3@gmail.com> X-Mailer: git-send-email 2.28.0 In-Reply-To: <20201002121645.23646-1-colomar.6.4.3@gmail.com> References: <20201002121645.23646-1-colomar.6.4.3@gmail.com> MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Spam-Status: No, score=-9.3 required=5.0 tests=BAYES_00, DKIM_SIGNED, DKIM_VALID, DKIM_VALID_AU, DKIM_VALID_EF, FREEMAIL_ENVFROM_END_DIGIT, FREEMAIL_FROM, GIT_PATCH_0, KAM_ASCII_DIVIDERS, RCVD_IN_DNSWL_NONE, SPF_HELO_NONE, SPF_PASS, TXREP autolearn=ham autolearn_force=no version=3.4.2 X-Spam-Checker-Version: SpamAssassin 3.4.2 (2018-09-13) on server2.sourceware.org X-BeenThere: libc-alpha@sourceware.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: Libc-alpha mailing list <libc-alpha.sourceware.org> List-Unsubscribe: <https://sourceware.org/mailman/options/libc-alpha>, <mailto:libc-alpha-request@sourceware.org?subject=unsubscribe> List-Archive: <https://sourceware.org/pipermail/libc-alpha/> List-Post: <mailto:libc-alpha@sourceware.org> List-Help: <mailto:libc-alpha-request@sourceware.org?subject=help> List-Subscribe: <https://sourceware.org/mailman/listinfo/libc-alpha>, <mailto:libc-alpha-request@sourceware.org?subject=subscribe> From: Alejandro Colomar via Libc-alpha <libc-alpha@sourceware.org> Reply-To: Alejandro Colomar <colomar.6.4.3@gmail.com> Cc: linux-man@vger.kernel.org, jwakely.gcc@gmail.com, libc-alpha@sourceware.org, Alejandro Colomar <colomar.6.4.3@gmail.com>, linux-kernel@vger.kernel.org, David.Laight@ACULAB.COM, gcc-patches@gcc.gnu.org Errors-To: libc-alpha-bounces@sourceware.org Sender: "Libc-alpha" <libc-alpha-bounces@sourceware.org> |
Series |
[v4,1/2] system_data_types.7: Add 'void *'
|
|
Commit Message
Alejandro Colomar
Oct. 2, 2020, 3:14 p.m. UTC
Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com> system_data_types.7: void *: Add info about generic function parameters and return value Reported-by: Paul Eggert <eggert@cs.ucla.edu> Reported-by: David Laight <David.Laight@ACULAB.COM> Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com> system_data_types.7: void *: Add info about pointer artihmetic Reported-by: Paul Eggert <eggert@cs.ucla.edu> Reported-by: David Laight <David.Laight@ACULAB.COM> Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com> system_data_types.7: void *: Add Versions notes Compatibility between function pointers and void * hasn't always been so. Document when that was added to POSIX. Reported-by: Michael Kerrisk <mtk.manpages@gmail.com> Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com> --- man7/system_data_types.7 | 80 +++++++++++++++++++++++++++++++++++++++- 1 file changed, 78 insertions(+), 2 deletions(-)
Comments
On 10/2/20 8:14 AM, Alejandro Colomar wrote: > +.I void * GNU style is a space between "void" and "*", so this should be '.I "void\ *"', both here and elsewhere. The backslash prevents a line break. > +Conversions from and to any other pointer type are done implicitly, > +not requiring casts at all. > +Note that this feature prevents any kind of type checking: > +the programmer should be careful not to cast a Change "cast" to "convert", since the point is that no cast is needed. > +.PP > +The conversion specifier for > +.I void * > +for the > +.BR printf (3) > +and the > +.BR scanf (3) > +families of functions is > +.BR p ; > +resulting commonly in > +.B %p > +for printing > +.I void * > +values. %p works with any object pointer type (or in POSIX, any pointer type), not just void *. Should also mention "void const *", "void volatile *", etc. Plus it really should talk about plain "void", saying that it's a placeholder as a return value for functions, for casting away values, and as a keyword in C11 for functions with no parameters (though this is being changed in the next C version!). I sent comments about most of this stuff already.
Hi Paul, On 2020-10-02 18:53, Paul Eggert wrote: > On 10/2/20 8:14 AM, Alejandro Colomar wrote: > >> +.I void * > > GNU style is a space between "void" and "*", so this should be '.I > "void\ *"', both here and elsewhere. The backslash prevents a line break. .I void * renders with a space in between. I'll show you the rendered version at the end of this email. > >> +Conversions from and to any other pointer type are done implicitly, >> +not requiring casts at all. >> +Note that this feature prevents any kind of type checking: >> +the programmer should be careful not to cast a > > Change "cast" to "convert", since the point is that no cast is needed. Ok. > >> +.PP >> +The conversion specifier for >> +.I void * >> +for the >> +.BR printf (3) >> +and the >> +.BR scanf (3) >> +families of functions is >> +.BR p ; >> +resulting commonly in >> +.B %p >> +for printing >> +.I void * >> +values. > > %p works with any object pointer type (or in POSIX, any pointer type), > not just void *. In theory, no (if otherwise, I'd like to know why): [[ p The argument shall be a pointer to void. The value of the pointer is converted to a sequence of printable characters, in an implementation-defined manner. ]] POSIX.1-2008 However, it's unlikely to cause any problems, I must admit. > > Should also mention "void const *", "void volatile *", etc. I already answered to this: https://lore.kernel.org/linux-man/CAH6eHdQhh46TjVc72meWFTWCi7iouAod0iC1zLRga+c-36G+ig@mail.gmail.com/T/#m6f657e988558a556cb70f7c056ef7a24e73dbe4a > Plus it > really should talk about plain "void", saying that it's a placeholder as > a return value for functions, for casting away values, and as a keyword > in C11 for functions with no parameters (though this is being changed in > the next C version!). I sent comments about most of this stuff already. 'void' is a completely different type from 'void *'. This patch is for 'void *'. If 'void' is documented, it'll be in a different entry (although in the same page), and therefore, that'll be for a different patch. Thanks, Alex
On 10/2/20 11:38 AM, Alejandro Colomar wrote: > .I void * > > renders with a space in between. That's odd, as "man(7)" says "All of the arguments will be printed next to each other without intervening spaces". I'd play it safe and quote the arg anyway. > > %p works with any object pointer type (or in POSIX, any pointer type), > > not just void *. > In theory, no (if otherwise, I'd like to know why): Oh, you're right. I had missed that. In GNU/Linux hosts, though, any pointer (including function pointers) can be given to %p. The only platforms where %p wouldn't work on all pointers would be platforms like IBM i, which has both 64-bit (process local) pointers and 128-bit (tagged space) pointers and where you can declare and use pointers of different widths in the same program.
Hi Paul, On 2020-10-02 22:14, Paul Eggert wrote: > On 10/2/20 11:38 AM, Alejandro Colomar wrote: > >> .I void * >> >> renders with a space in between. > > That's odd, as "man(7)" says "All of the arguments will be printed next > to each other without intervening spaces". I'd play it safe and quote > the arg anyway. Oops, that's a bug in man(7). Don't worry about it. Michael, you might want to have a look at it. I'll also add Branden, who might have something to say about it. > >> > %p works with any object pointer type (or in POSIX, any pointer type), >> > not just void *. >> In theory, no (if otherwise, I'd like to know why): > > Oh, you're right. I had missed that. In GNU/Linux hosts, though, any > pointer (including function pointers) can be given to %p. > > The only platforms where %p wouldn't work on all pointers would be > platforms like IBM i, which has both 64-bit (process local) pointers and > 128-bit (tagged space) pointers and where you can declare and use > pointers of different widths in the same program. :-) Cheers, Alex
On 10/2/20 10:27 PM, Alejandro Colomar wrote: > Hi Paul, > > On 2020-10-02 22:14, Paul Eggert wrote: > > On 10/2/20 11:38 AM, Alejandro Colomar wrote: > > > >> .I void * > >> > >> renders with a space in between. > > > > That's odd, as "man(7)" says "All of the arguments will be printed next > > to each other without intervening spaces". I'd play it safe and quote > > the arg anyway. > > Oops, that's a bug in man(7). > Don't worry about it. I'm not sure where that text in man(7) comes from. However, for clarity I would normally also use quotes in this case. > Michael, you might want to have a look at it. > > I'll also add Branden, who might have something to say about it. Yes, maybe Branden can add some insight. Thanks, Michael
At 2020-10-03T09:10:14+0200, Michael Kerrisk (man-pages) wrote: > On 10/2/20 10:27 PM, Alejandro Colomar wrote: > > On 2020-10-02 22:14, Paul Eggert wrote: > > > On 10/2/20 11:38 AM, Alejandro Colomar wrote: > > > > > >> .I void * > > >> > > >> renders with a space in between. > > > > > > That's odd, as "man(7)" says "All of the arguments will be > > > printed next to each other without intervening spaces". I'd play > > > it safe and quote the arg anyway. > > > > Oops, that's a bug in man(7). Don't worry about it. > > I'm not sure where that text in man(7) comes from. However, for > clarity I would normally also use quotes in this case. > > > Michael, you might want to have a look at it. > > > > I'll also add Branden, who might have something to say about it. > > Yes, maybe Branden can add some insight. The "short" answer[1] is that I think Alex is correct; Paul's caution is unwarranted and arises from confusion with the font alternation macros of the man(7) macro package. Examples of the latter are .BI and .BR. Those set their even-numbered arguments in one font and odd-numbered arguments in another, with no space between them. That suppression of space is the reason they exist. With the "single-font" macros like .B and .I[2], if you don't want space, don't type it. I could say more, including an annotated explanation of the groff and Version 7 Unix man(7) implementations of the I macro, if desired. :) Regards, Branden [1] since as everyone knows, I struggle with brevity [2] I (and others) discourage use of .SM and .SB because they can't be distinguished from ordinary roman and bold type, respectively, on terminals.
Hi Michael and Branden, On 2020-10-03 09:48, G. Branden Robinson wrote: > At 2020-10-03T09:10:14+0200, Michael Kerrisk (man-pages) wrote: >> On 10/2/20 10:27 PM, Alejandro Colomar wrote: >>> On 2020-10-02 22:14, Paul Eggert wrote: >>> > On 10/2/20 11:38 AM, Alejandro Colomar wrote: >>> > >>> >> .I void * >>> >> >>> >> renders with a space in between. >>> > >>> > That's odd, as "man(7)" says "All of the arguments will be >>> > printed next to each other without intervening spaces". I'd play >>> > it safe and quote the arg anyway. >>> >>> Oops, that's a bug in man(7). Don't worry about it. >> >> I'm not sure where that text in man(7) comes from. However, for >> clarity I would normally also use quotes in this case. Hi Michael and Branden, Here is the offending line: https://git.kernel.org/pub/scm/docs/man-pages/man-pages.git/tree/man7/man.7#n172 Thanks, Alex >> >>> Michael, you might want to have a look at it. >>> >>> I'll also add Branden, who might have something to say about it. >> >> Yes, maybe Branden can add some insight. > > The "short" answer[1] is that I think Alex is correct; Paul's caution is > unwarranted and arises from confusion with the font alternation macros > of the man(7) macro package. Examples of the latter are .BI and .BR. > Those set their even-numbered arguments in one font and odd-numbered > arguments in another, with no space between them. That suppression of > space is the reason they exist. With the "single-font" macros like .B > and .I[2], if you don't want space, don't type it. > > I could say more, including an annotated explanation of the groff and > Version 7 Unix man(7) implementations of the I macro, if desired. :) > > Regards, > Branden > > [1] since as everyone knows, I struggle with brevity > [2] I (and others) discourage use of .SM and .SB because they can't be > distinguished from ordinary roman and bold type, respectively, on > terminals. >
On 10/3/20 9:48 AM, G. Branden Robinson wrote: [...] >> The "short" answer[1] is that I think Alex is correct; Paul's caution is >> unwarranted and arises from confusion with the font alternation macros >> of the man(7) macro package. Examples of the latter are .BI and .BR. >> Those set their even-numbered arguments in one font and odd-numbered >> arguments in another, with no space between them. That suppression of >> space is the reason they exist. With the "single-font" macros like .B >> and .I[2], if you don't want space, don't type it. Hi Branden, This explanation is great :) Would you mind writing a patch with it? Cheers, Alex >> >> I could say more, including an annotated explanation of the groff and >> Version 7 Unix man(7) implementations of the I macro, if desired. :) :) >> >> Regards, >> Branden >> >> [1] since as everyone knows, I struggle with brevity >> [2] I (and others) discourage use of .SM and .SB because they can't be >> distinguished from ordinary roman and bold type, respectively, on >> terminals. >>
On 10/3/20 9:48 AM, G. Branden Robinson wrote: > At 2020-10-03T09:10:14+0200, Michael Kerrisk (man-pages) wrote: >> On 10/2/20 10:27 PM, Alejandro Colomar wrote: >>> On 2020-10-02 22:14, Paul Eggert wrote: >>> > On 10/2/20 11:38 AM, Alejandro Colomar wrote: >>> > >>> >> .I void * >>> >> >>> >> renders with a space in between. >>> > >>> > That's odd, as "man(7)" says "All of the arguments will be >>> > printed next to each other without intervening spaces". I'd play >>> > it safe and quote the arg anyway. >>> >>> Oops, that's a bug in man(7). Don't worry about it. >> >> I'm not sure where that text in man(7) comes from. However, for >> clarity I would normally also use quotes in this case. >> >>> Michael, you might want to have a look at it. >>> >>> I'll also add Branden, who might have something to say about it. >> >> Yes, maybe Branden can add some insight. > > The "short" answer[1] is that I think Alex is correct; Paul's caution is > unwarranted and arises from confusion with the font alternation macros > of the man(7) macro package. Examples of the latter are .BI and .BR. > Those set their even-numbered arguments in one font and odd-numbered > arguments in another, with no space between them. That suppression of > space is the reason they exist. With the "single-font" macros like .B > and .I[2], if you don't want space, don't type it. > > I could say more, including an annotated explanation of the groff and > Version 7 Unix man(7) implementations of the I macro, if desired. :) So, perhaps change: All of the arguments will be printed next to each other without intervening spaces, so that the .BR command can be used to specify a word in bold followed by a mark of punctuation in Roman. to: For the macros that produce alternating type faces, the arguments will be printed next to each other without intervening spaces, so that the .BR command can be used to specify a word in bold followed by a mark of punctuation in Roman. ? > [1] since as everyone knows, I struggle with brevity > [2] I (and others) discourage use of .SM and .SB because they can't be > distinguished from ordinary roman and bold type, respectively, on > terminals. So, do you think it's worth discouraging this in man(7)? Thanks, Michael
diff --git a/man7/system_data_types.7 b/man7/system_data_types.7 index c82d3b388..277e05b12 100644 --- a/man7/system_data_types.7 +++ b/man7/system_data_types.7 @@ -679,7 +679,6 @@ See also the .I uintptr_t and .I void * -.\" TODO: Document void * types in this page. .RE .\"------------------------------------- lconv ------------------------/ @@ -1780,7 +1779,6 @@ See also the .I intptr_t and .I void * -.\" TODO: Document void * types in this page. .RE .\"------------------------------------- va_list ----------------------/ @@ -1814,6 +1812,84 @@ See also: .BR va_copy (3), .BR va_end (3) .RE +.\"------------------------------------- void * -----------------------/ +.TP +.I void * +.RS +According to the C language standard, +a pointer to any object type may be converted to a pointer to +.I void +and back. +POSIX further requires that any pointer, +including pointers to functions, +may be converted to a pointer to +.I void +and back. +.PP +Conversions from and to any other pointer type are done implicitly, +not requiring casts at all. +Note that this feature prevents any kind of type checking: +the programmer should be careful not to cast a +.I void * +value to a type incompatible to that of the underlying data, +because that would result in undefined behavior. +.PP +This type is useful in function parameters and return value +to allow passing values of any type. +The function will usually use some mechanism to know +of which type the underlying data passed to the function really is. +.PP +A value of this type can't be dereferenced, +as it would give a value of type +.I void +which is not possible. +Likewise, pointer arithmetic is not possible with this type. +However, in GNU C, poitner arithmetic is allowed +as an extension to the standard; +this is done by treating the size of a +.I void +or of a function as 1. +A consequence of this is that +.I sizeof +is also allowed on +.I void +and on function types, and returns 1. +.PP +The conversion specifier for +.I void * +for the +.BR printf (3) +and the +.BR scanf (3) +families of functions is +.BR p ; +resulting commonly in +.B %p +for printing +.I void * +values. +.PP +Versions: +The POSIX requirement about compatibility between +.I void * +and function pointers was added in +POSIX.1-2008 Technical Corrigendum 1 (2013). +.PP +Conforming to: +C99 and later; POSIX.1-2001 and later. +.PP +See also: +.BR malloc (3), +.BR memcmp (3), +.BR memcpy (3), +.BR memset (3) +.PP +See also the +.I intptr_t +and +.I uintptr_t +types in this page. +.RE .\"--------------------------------------------------------------------/ .SH NOTES The structures described in this manual page shall contain,