Received: by 2002:a05:6a10:22f:0:0:0:0 with SMTP id 15csp1297522pxk; Fri, 2 Oct 2020 06:17:30 -0700 (PDT) X-Google-Smtp-Source: ABdhPJxv3dlW9ZqndFTUT/utkm0Oy5ncIgUlsqEJ9vgs/Gii2Oba+u2C+dy94/lNSulcFInhzhna X-Received: by 2002:a05:6402:1773:: with SMTP id da19mr2166732edb.171.1601644649844; Fri, 02 Oct 2020 06:17:29 -0700 (PDT) ARC-Seal: i=1; a=rsa-sha256; t=1601644649; cv=none; d=google.com; s=arc-20160816; b=DqW7EHTAyQIQmispWGqD9m6qW3h2ZMe+awsx/jR9DJtEtXobqK28COT6CQ9litJhI/ BEAl7hFOl0mY+pVzNMCjyOgYS3sOKDip5vm1616txrx3plfAYNf8aPfcYsosxi/jzseb vVG4bttTjmuA0phixL1GXLEdCl8wUq3X0yiYCb06zZutt8bS9xyu5xLAANEv7zUMON/8 0EKaPPxRymPkQmI2ghLzngFyh1FaP7UPc5vkqpLXtDnknrqkqy0R7iC9IymdWd9qFP9O Bgdt3q4WntYydnMQimWxih7O7a7J1jV5fVxX5eoFkVCR50CH9LyCKpiaOImgOCJm6+5Q gqTw== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=list-id:precedence:cc:to:subject:message-id:date:from:in-reply-to :references:mime-version:dkim-signature; bh=NV9+yrJq+JbCr6cFYFd6SzA3+a52bQ0Cmy5QJDHiFvU=; b=wmQzu60rI3SjVC4DnRiiaw4oecigqogUSFwbSYK7dbf5cZK/W6YyxRI8jGURGJIIr/ sZMylqp5dKkBA40owL+lMXdwTjHX3qk9n/PhRH5pF6c400y1nermVg5pluLf+bcxgXCB SRQH6yyD/7l+LA56rAW32skBveWhRVLP2bb0hbP8zyGfLbS68+nktP46Gomhzr78zqeX zOxZyPlS87yB2SnsZepmHSVFerGjtKtVu+q1V6bqXGgDu4unEK0CGDsUPyTqR3hW7aBa GF3GRkEM1qCoB3ODVh3uOUJt0cmWCboH81ENKqG/oPCCtL86uW8w3TDnK3bz/TQr6BzJ A0BQ== ARC-Authentication-Results: i=1; mx.google.com; dkim=pass header.i=@gmail.com header.s=20161025 header.b=itIlg738; spf=pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 23.128.96.18 as permitted sender) smtp.mailfrom=linux-kernel-owner@vger.kernel.org; dmarc=pass (p=NONE sp=QUARANTINE dis=NONE) header.from=gmail.com Return-Path: Received: from vger.kernel.org (vger.kernel.org. [23.128.96.18]) by mx.google.com with ESMTP id t22si1025990eji.298.2020.10.02.06.17.07; Fri, 02 Oct 2020 06:17:29 -0700 (PDT) Received-SPF: pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 23.128.96.18 as permitted sender) client-ip=23.128.96.18; Authentication-Results: mx.google.com; dkim=pass header.i=@gmail.com header.s=20161025 header.b=itIlg738; spf=pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 23.128.96.18 as permitted sender) smtp.mailfrom=linux-kernel-owner@vger.kernel.org; dmarc=pass (p=NONE sp=QUARANTINE dis=NONE) header.from=gmail.com Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S2387862AbgJBNPz (ORCPT + 99 others); Fri, 2 Oct 2020 09:15:55 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:43146 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S2387767AbgJBNPz (ORCPT ); Fri, 2 Oct 2020 09:15:55 -0400 Received: from mail-io1-xd44.google.com (mail-io1-xd44.google.com [IPv6:2607:f8b0:4864:20::d44]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 649C0C0613D0; Fri, 2 Oct 2020 06:15:55 -0700 (PDT) Received: by mail-io1-xd44.google.com with SMTP id y74so1450014iof.12; Fri, 02 Oct 2020 06:15:55 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20161025; h=mime-version:references:in-reply-to:from:date:message-id:subject:to :cc; bh=NV9+yrJq+JbCr6cFYFd6SzA3+a52bQ0Cmy5QJDHiFvU=; b=itIlg738Y5xIaieU692HUBFF9lhBPxXt9di1Vf2sK41x0wWb6U6QH5BYo0bwkYsx/A KANxg7AHYiX2jPcZ0PSh9uL19ETw6UQXs0c7U7PmLlYeRVesZ3mk9d26yLeIss/HZYpB VqiG2B9ITR4OiWuuIFdPKgdL4ojk6E2gAho7G+FA7hpigx+RbPJVg8XWBsCRe38tdh7K tlYK09GWkGYcERNxC91x0xYlAwp7tYt4GwNZCgHTSF4P+VgeIRKXzbKjpxYpFnQ1U2HP V4kZvNFQ1ZxmuJ2F69nkqaUF4DaF+7ThmkziWkgveEJqNPJayAKDrZeZWK79ngwyX0vI 9BKQ== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:mime-version:references:in-reply-to:from:date :message-id:subject:to:cc; bh=NV9+yrJq+JbCr6cFYFd6SzA3+a52bQ0Cmy5QJDHiFvU=; b=b1o7Wp+TQHmrNBk5sNvoHRMzvDwmjnBH5/0Ou9eoxtPtW45JfPUFT89hhkNl63Ms7r ThE9fAtV3nJsJCPOlz/54p55zoRHaiuqoZJgqOLlV7ICJZVkA9rN8DUeJTi5h/CRUgwv lHO+L+V6V0c9t30+rWqrqTFLgcD2yCUXxU3q0gslmtTi6XEUsgZ9BwwAFZo2G8u/aqF5 2nBhBIKyXYBDcRYlq0080fz10oTuAHfmMYKrmgO1hBF17zZ+vs5Tg5nhblXuX0jTgrPz N0DEJzJseJn/Yu52voQSHSej4FBnavoGer0nkZy53YrYtBlLJRyB6I1dn9i9Ousx7Rsp rqZQ== X-Gm-Message-State: AOAM530OPqryXm9pjKOxsqSz/D1I0pl7ET64P9PJvvmLAEf785fLwneW 3Qp0AxJXKYGF2jk2O4l8gZPlvxZA6aIKgBks20ogrJrL X-Received: by 2002:a02:e47:: with SMTP id 68mr2161854jae.78.1601644554674; Fri, 02 Oct 2020 06:15:54 -0700 (PDT) MIME-Version: 1.0 References: <20201002121645.23646-1-colomar.6.4.3@gmail.com> <20201002121645.23646-2-colomar.6.4.3@gmail.com> In-Reply-To: <20201002121645.23646-2-colomar.6.4.3@gmail.com> From: Jonathan Wakely Date: Fri, 2 Oct 2020 14:15:43 +0100 Message-ID: Subject: Re: [PATCH 1/2] system_data_types.7: Add 'void *' To: Alejandro Colomar Cc: "Michael Kerrisk (man-pages)" , linux-man , gcc-patches , GNU C Library , linux-kernel@vger.kernel.org, eggert@cs.ucla.edu, David.Laight@aculab.com Content-Type: text/plain; charset="UTF-8" Precedence: bulk List-ID: X-Mailing-List: linux-kernel@vger.kernel.org On Fri, 2 Oct 2020 at 13:17, Alejandro Colomar wrote: > > Signed-off-by: Alejandro Colomar > > system_data_types.7: void *: Add info about generic function parameters and return value > > Reported-by: Paul Eggert > Reported-by: David Laight > Signed-off-by: Alejandro Colomar > > system_data_types.7: void *: Add info about pointer artihmetic > > Reported-by: Paul Eggert > Reported-by: David Laight > Signed-off-by: Alejandro Colomar > > 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 > Signed-off-by: Alejandro Colomar > --- > man7/system_data_types.7 | 80 +++++++++++++++++++++++++++++++++++++++- > 1 file changed, 78 insertions(+), 2 deletions(-) > > 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. This sentence seems clunky. How about "The function will typically use some mechanism to know the real type of the data being passed via a pointer to void." An example of "some mechanism" might be useful, though I don't have one to offer. > +.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 Typo: pointer > +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. What does "resulting commonly in %p for printing void * values" mean? Is this just explaining that the format specifier p is commonly used as "%p" (but sometimes as e.g. "%20p") ? I'm not sure the "resulting commonly ..." part adds anything of value, rather than just being confusing. > +.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, > -- > 2.28.0 >