From: Alejandro Colomar <colomar.6.4.3@gmail.com>
To: mtk.manpages@gmail.com
Cc: Alejandro Colomar <colomar.6.4.3@gmail.com>,
linux-man@vger.kernel.org, gcc-patches@gcc.gnu.org,
libc-alpha@sourceware.org, eggert@cs.ucla.edu,
linux-kernel@vger.kernel.org, jwakely.gcc@gmail.com,
David.Laight@ACULAB.COM
Subject: [PATCH v5 1/2] system_data_types.7: Add 'void *'
Date: Fri, 2 Oct 2020 21:28:15 +0200 [thread overview]
Message-ID: <20201002192814.14113-2-colomar.6.4.3@gmail.com> (raw)
In-Reply-To: <20201002151419.32053-1-colomar.6.4.3@gmail.com>
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>
system_data_types.7: void *: wfix
Reported-by: Jonathan Wakely <jwakely.gcc@gmail.com>
Reported-by: Paul Eggert <eggert@cs.ucla.edu>
Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com>
---
man7/system_data_types.7 | 76 ++++++++++++++++++++++++++++++++++++++--
1 file changed, 74 insertions(+), 2 deletions(-)
diff --git a/man7/system_data_types.7 b/man7/system_data_types.7
index c82d3b388..7c1198802 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,80 @@ 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 convert 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 typically use some mechanism to know
+the real type of the data being passed via a pointer to
+.IR void .
+.PP
+A value of this type can't be dereferenced,
+as it would give a value of type
+.IR void ,
+which is not possible.
+Likewise, pointer arithmetic is not possible with this type.
+However, in GNU C, pointer 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 .
+.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
next prev parent reply other threads:[~2020-10-02 19:33 UTC|newest]
Thread overview: 22+ messages / expand[flat|nested] mbox.gz Atom feed top
2020-10-02 12:16 [PATCH 0/2] Document 'void *' Alejandro Colomar
2020-10-02 12:16 ` [PATCH 1/2] system_data_types.7: Add " Alejandro Colomar
2020-10-02 13:15 ` Jonathan Wakely
2020-10-02 13:26 ` David Laight
2020-10-02 12:16 ` [PATCH 2/2] void.3: New link to system_data_types(7) Alejandro Colomar
2020-10-02 15:14 ` [PATCH v4 0/2] Document 'void *' Alejandro Colomar
2020-10-02 19:28 ` [PATCH v5 " Alejandro Colomar
2020-10-02 19:28 ` Alejandro Colomar [this message]
2020-10-03 8:01 ` [PATCH v5 1/2] system_data_types.7: Add " Michael Kerrisk (man-pages)
2020-10-02 19:28 ` [PATCH v5 2/2] void.3: New link to system_data_types(7) Alejandro Colomar
2020-10-03 8:01 ` Michael Kerrisk (man-pages)
2020-10-02 15:14 ` [PATCH v4 1/2] system_data_types.7: Add 'void *' Alejandro Colomar
2020-10-02 16:53 ` Paul Eggert
2020-10-02 18:38 ` Alejandro Colomar
2020-10-02 20:14 ` Paul Eggert
2020-10-02 20:27 ` Alejandro Colomar
2020-10-03 7:10 ` Michael Kerrisk (man-pages)
2020-10-03 7:48 ` G. Branden Robinson
2020-10-03 8:55 ` Alejandro Colomar
2020-10-03 11:47 ` Alejandro Colomar
2020-10-03 11:52 ` Michael Kerrisk (man-pages)
2020-10-02 15:14 ` [PATCH v4 2/2] void.3: New link to system_data_types(7) Alejandro Colomar
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20201002192814.14113-2-colomar.6.4.3@gmail.com \
--to=colomar.6.4.3@gmail.com \
--cc=David.Laight@ACULAB.COM \
--cc=eggert@cs.ucla.edu \
--cc=gcc-patches@gcc.gnu.org \
--cc=jwakely.gcc@gmail.com \
--cc=libc-alpha@sourceware.org \
--cc=linux-kernel@vger.kernel.org \
--cc=linux-man@vger.kernel.org \
--cc=mtk.manpages@gmail.com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).