From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mail-io1-xd42.google.com (mail-io1-xd42.google.com [IPv6:2607:f8b0:4864:20::d42]) by sourceware.org (Postfix) with ESMTPS id 5FB3C384A034 for ; Fri, 2 Oct 2020 13:15:55 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.3.2 sourceware.org 5FB3C384A034 Received: by mail-io1-xd42.google.com with SMTP id k25so1464285ioh.7 for ; Fri, 02 Oct 2020 06:15:55 -0700 (PDT) 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=m5oa0xg6m3cqsFLxKcAksq0VOUYzLjhJ/wFicwDDuqhdw1CApS93SLSDx7FyN7+BmI wZCrApiChuYopw2YsBam2tljoqkZsHkc+HD3V20BkVx6mk14M72l3VBedWWaqKuhfXxV J3o+0egQp9iFH2zUOsFMpKZFx+NB716S+td4ZoJpcXHNePl0hVj3Cwcd4ZsBWURTrHLT sAlUE/i1sfbq3xW1E2EIU6yzlj7zg68MbwFLKoPwvrGEj+zGzjjfuBxwdH3Xl1hkSCWJ zso7tTkDwGXgCHLllxfEVLwYJ4sRX0M9acqbSY60OnOeaNSHcRIT8mj3D6Tyf65kB0QJ DSwA== X-Gm-Message-State: AOAM530vVCGKhXRJgpkiHTAmmOG5pQAEgM/Q66HR1oEiju30lM5GTjHR juqr61RIYBXbs3YvhK/Dh91Gvw4AifweHHGFWvQ= X-Google-Smtp-Source: ABdhPJwnNOqEg0c0RLPVInz9CgNB2jGjdrykkIa9igU9sNmuqp7vWpk5J62LSsNldqh8FpRt80vyDEDHZzM8eWUauIY= 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" X-Spam-Status: No, score=-9.7 required=5.0 tests=BAYES_00, DKIM_SIGNED, DKIM_VALID, DKIM_VALID_AU, DKIM_VALID_EF, 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 List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Fri, 02 Oct 2020 13:15:56 -0000 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 >