[PATCH 0/2] Document 'void *'

[PATCH 0/2] Document 'void *'

[Alejandro Colomar]

Hi Michael,

As you asked, I squashed.
And added the POSIX.1-2008 note too. Thanks for that!

Cheers,

Alex

Alejandro Colomar (2):
  system_data_types.7: Add 'void *'
  void.3: New link to system_data_types(7)

 man3/void.3              |  1 +
 man7/system_data_types.7 | 80 +++++++++++++++++++++++++++++++++++++++-
 2 files changed, 79 insertions(+), 2 deletions(-)
 create mode 100644 man3/void.3

-- 
2.28.0

[PATCH 1/2] system_data_types.7: Add 'void *'

[Alejandro Colomar]

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(-)

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,
-- 
2.28.0

Re: [PATCH 1/2] system_data_types.7: Add 'void *'

[Jonathan Wakely]

On Fri, 2 Oct 2020 at 13:17, Alejandro Colomar <colomar.6.4.3@gmail.com> wrote:
>
> 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(-)
>
> 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
>

RE: [PATCH 1/2] system_data_types.7: Add 'void *'

[David Laight]

> > +.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.

It's also bollocks.

There are two main places 'void *' is used:
1) buffers (eg functions like read() and write()) when the
   associated byte length is also passed.
   This (sort of) includes memory allocation functions.
2) Passing a parameter for a callback function.
   In this case the pointer is always cast back to
   the original type before being used.
   
What it shouldn't be used for is structures you don't
want other code to look inside - use incomplete structs.

	David

-
Registered Address Lakeside, Bramley Road, Mount Farm, Milton Keynes, MK1 1PT, UK
Registration No: 1397386 (Wales)

[PATCH 2/2] void.3: New link to system_data_types(7)

[Alejandro Colomar]

Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com>
---
 man3/void.3 | 1 +
 1 file changed, 1 insertion(+)
 create mode 100644 man3/void.3

diff --git a/man3/void.3 b/man3/void.3
new file mode 100644
index 000000000..db50c0f09
--- /dev/null
+++ b/man3/void.3
@@ -0,0 +1 @@
+.so man7/system_data_types.7
-- 
2.28.0

[PATCH v4 0/2] Document 'void *'

[Alejandro Colomar]

Hi Michael,

I'm sorry I forgot to increase the version count.
And given there are conversations continuing in old threads,
you may mix them easily.  I'm a bit lost in the emails too.
I'll resend the latest patch (identically) as v4
(there's no v3, but this is the 4th time or so, so let's call it v4).

Regards,

Alex

Alejandro Colomar (2):
  system_data_types.7: Add 'void *'
  void.3: New link to system_data_types(7)

 man3/void.3              |  1 +
 man7/system_data_types.7 | 80 +++++++++++++++++++++++++++++++++++++++-
 2 files changed, 79 insertions(+), 2 deletions(-)
 create mode 100644 man3/void.3

-- 
2.28.0

[PATCH v5 0/2] Document 'void *'

[Alejandro Colomar]

Hi Michael,

Here I added a wfix fixing some wording issues and a few typos
spotted by Paul and Jonathan in the (many) threads.
As previously, it is squashed into a single commit.


Thanks again for those who reviewed the patch!

BTW, for those who don't have a local repo of the man-pages,
below you can see a rendered version of the patch.

Thanks,

Alex

[[
void *
      According  to  the  C language standard, a pointer to any object
      type may be converted to a pointer to void and back.  POSIX fur-
      ther requires that any pointer, including pointers to functions,
      may be converted to a pointer to void and back.

      Conversions from and to any other pointer type are done  implic-
      itly,  not  requiring casts at all.  Note that this feature pre-
      vents any kind of type checking: the programmer should be  care-
      ful not to convert a void * value to a type incompatible to that
      of the underlying data, because that would result  in  undefined
      behavior.

      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 void.

      A value of this type can't be dereferenced, as it would  give  a
      value  of  type  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 void or of a function  as
      1.  A consequence of this is that sizeof is also allowed on void
      and on function types, and returns 1.

      The conversion specifier for void * for the  printf(3)  and  the
      scanf(3) families of functions is p.

      Versions: The POSIX requirement about compatibility between void
      * and function pointers was added in POSIX.1-2008 Technical Cor-
      rigendum 1 (2013).

      Conforming to: C99 and later; POSIX.1-2001 and later.

      See also: malloc(3), memcmp(3), memcpy(3), memset(3)

      See also the intptr_t and uintptr_t types in this page.
]]


Alejandro Colomar (2):
  system_data_types.7: Add 'void *'
  void.3: New link to system_data_types(7)

 man3/void.3              |  1 +
 man7/system_data_types.7 | 76 ++++++++++++++++++++++++++++++++++++++--
 2 files changed, 75 insertions(+), 2 deletions(-)
 create mode 100644 man3/void.3

-- 
2.28.0

[PATCH v5 1/2] system_data_types.7: Add 'void *'

[Alejandro Colomar]

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

Re: [PATCH v5 1/2] system_data_types.7: Add 'void *'

[Michael Kerrisk (man-pages)]

Hello Alex,

On 10/2/20 9:28 PM, Alejandro Colomar wrote:
> Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com>

Patch applied.

Thanks,

Michael


> 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,
> 


-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/

[PATCH v5 2/2] void.3: New link to system_data_types(7)

[Alejandro Colomar]

Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com>
---
 man3/void.3 | 1 +
 1 file changed, 1 insertion(+)
 create mode 100644 man3/void.3

diff --git a/man3/void.3 b/man3/void.3
new file mode 100644
index 000000000..db50c0f09
--- /dev/null
+++ b/man3/void.3
@@ -0,0 +1 @@
+.so man7/system_data_types.7
-- 
2.28.0

Re: [PATCH v5 2/2] void.3: New link to system_data_types(7)

[Michael Kerrisk (man-pages)]

Hello Alex,

On 10/2/20 9:28 PM, Alejandro Colomar wrote:
> Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com>

Patch applied.

And, I think we're now at a sync point.

Thanks,

Michael


> ---
>  man3/void.3 | 1 +
>  1 file changed, 1 insertion(+)
>  create mode 100644 man3/void.3
> 
> diff --git a/man3/void.3 b/man3/void.3
> new file mode 100644
> index 000000000..db50c0f09
> --- /dev/null
> +++ b/man3/void.3
> @@ -0,0 +1 @@
> +.so man7/system_data_types.7
> 


-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/

[PATCH v4 1/2] system_data_types.7: Add 'void *'

[Alejandro Colomar]

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(-)

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,
-- 
2.28.0

Re: [PATCH v4 1/2] system_data_types.7: Add 'void *'

[Paul Eggert]

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.

Re: [PATCH v4 1/2] system_data_types.7: Add 'void *'

[Alejandro Colomar]

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

__________________

void *
       According  to  the  C language standard, a pointer to any object
       type may be converted to a pointer to void and back.  POSIX fur-
       ther requires that any pointer, including pointers to functions,
       may be converted to a pointer to void and back.

       Conversions from and to any other pointer type are done  implic-
       itly,  not  requiring casts at all.  Note that this feature pre-
       vents any kind of type checking: the programmer should be  care-
       ful not to cast a void * value to a type incompatible to that of
       the underlying data, because that would result in undefined  be-
       havior.

       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.

       A value of this type can't be dereferenced, as it would  give  a
       value  of  type  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 void or of a function  as
       1.  A consequence of this is that sizeof is also allowed on void
       and on function types, and returns 1.

       The conversion specifier for void * for the  printf(3)  and  the
       scanf(3)  families  of  functions is p; resulting commonly in %p
       for printing void * values.

       Versions: The POSIX requirement about compatibility between void
       * and function pointers was added in POSIX.1-2008 Technical Cor-
       rigendum 1 (2013).

       Conforming to: C99 and later; POSIX.1-2001 and later.

       See also: malloc(3), memcmp(3), memcpy(3), memset(3)

       See also the intptr_t and uintptr_t types in this page.

Re: [PATCH v4 1/2] system_data_types.7: Add 'void *'

[Paul Eggert]

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.

Re: [PATCH v4 1/2] system_data_types.7: Add 'void *'

[Alejandro Colomar]

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

Re: [PATCH v4 1/2] system_data_types.7: Add 'void *'

[Michael Kerrisk (man-pages)]

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

-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/

Re: [PATCH v4 1/2] system_data_types.7: Add 'void *'

[G. Branden Robinson]

[-- Attachment #1: Type: text/plain, Size: 1710 bytes --]

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.

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [PATCH v4 1/2] system_data_types.7: Add 'void *'

[Alejandro Colomar]

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.
> 

Re: [PATCH v4 1/2] system_data_types.7: Add 'void *'

[Alejandro Colomar]

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.
>>

Re: [PATCH v4 1/2] system_data_types.7: Add 'void *'

[Michael Kerrisk (man-pages)]

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
 


-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/

[PATCH v4 2/2] void.3: New link to system_data_types(7)

[Alejandro Colomar]

Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com>
---
 man3/void.3 | 1 +
 1 file changed, 1 insertion(+)
 create mode 100644 man3/void.3

diff --git a/man3/void.3 b/man3/void.3
new file mode 100644
index 000000000..db50c0f09
--- /dev/null
+++ b/man3/void.3
@@ -0,0 +1 @@
+.so man7/system_data_types.7
-- 
2.28.0