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

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

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
>
  

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