[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/