[src/trunk]: src/share/man/man3 Document __FPTRCAST

[christos <christos%NetBSD.org@localhost>]

details:   https://anonhg.NetBSD.org/src/rev/643e803de5d8
branches:  trunk
changeset: 846299:643e803de5d8
user:      christos <christos%NetBSD.org@localhost>
date:      Sun Nov 10 18:45:09 2019 +0000

description:
Document __FPTRCAST
XXX: more macros need documentation (__CAST etc.)

diffstat:

 share/man/man3/Makefile     |   4 +-
 share/man/man3/__FPTRCAST.3 |  79 +++++++++++++++++++++++++++++++++++++++++++++
 share/man/man3/cdefs.3      |  13 +++++-
 3 files changed, 91 insertions(+), 5 deletions(-)

diffs (139 lines):

diff -r 8e6eca27366c -r 643e803de5d8 share/man/man3/Makefile
--- a/share/man/man3/Makefile   Sun Nov 10 14:20:50 2019 +0000
+++ b/share/man/man3/Makefile   Sun Nov 10 18:45:09 2019 +0000
@@ -1,7 +1,7 @@
-#      $NetBSD: Makefile,v 1.88 2013/11/27 16:30:12 christos Exp $
+#      $NetBSD: Makefile,v 1.89 2019/11/10 18:45:09 christos Exp $
 #      @(#)Makefile    8.2 (Berkeley) 12/13/93
 
-MAN=   _DIAGASSERT.3 __CONCAT.3 __UNCONST.3 __USE.3 CMSG_DATA.3 \
+MAN=   _DIAGASSERT.3 __CONCAT.3 __FPTRCAST.3 __UNCONST.3 __USE.3 CMSG_DATA.3 \
        __alignof__.3 __arraycount.3 \
        __builtin_constant_p.3 __builtin_prefetch.3 \
        __builtin_return_address.3 \
diff -r 8e6eca27366c -r 643e803de5d8 share/man/man3/__FPTRCAST.3
--- /dev/null   Thu Jan 01 00:00:00 1970 +0000
+++ b/share/man/man3/__FPTRCAST.3       Sun Nov 10 18:45:09 2019 +0000
@@ -0,0 +1,79 @@
+.\"    $NetBSD: __FPTRCAST.3,v 1.1 2019/11/10 18:45:09 christos Exp $ $
+.\"
+.\" Copyright (c) 2019 The NetBSD Foundation, Inc.
+.\" All rights reserved.
+.\"
+.\" This code is derived from software contributed to The NetBSD Foundation
+.\" by Christos Zoulas
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\"    notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\"    notice, this list of conditions and the following disclaimer in the
+.\"    documentation and/or other materials provided with the distribution.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
+.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
+.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+.\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
+.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+.\" POSSIBILITY OF SUCH DAMAGE.
+.\"
+.Dd October 17, 2013
+.Dt __FPTRCAST 3
+.Os
+.Sh NAME
+.Nm __FPTRCAST ,
+.Nd function pointer cast
+.Sh SYNOPSIS
+.In sys/cdefs.h
+.Ft ftype
+.Fn __FPTRCAST ftype fname
+.Sh DESCRIPTION
+The
+.Fn __FPTRCAST
+macro can be used to silence warnings produced by certain compilers when
+converting from one function pointer type to another.
+The
+.Fa ftype
+argument is the function pointer type to cast the function pointer in
+.Fa fname .
+.Pp
+This cast should be used sparingly and it is typically used in the following
+situations:
+.Bl -bullet -offset indent -compact
+.It
+We know that the function prototypes don't match at all, but we don't care
+because we point it to a function that does not take arguments and returns
+an error. 
+.It
+We only care about the first few arguments and we don't care about the rest.
+.It
+We don't care about the return value, we ignore it anyway.
+.El
+.Sh IMPLEMENTATION NOTES
+This macro is implemented by using an intermediate
+.Em void *
+cast.
+.Sh SEE ALSO
+.Xr cc 1 ,
+.Xr cdefs 3
+.Sh CAVEATS
+Use of this macro can hide valid errors, and its usage is not recommended
+unless there is a well-thought reason for a cast.
+As a general guideline, don't use this macro inside other macros because
+it will hide cases where the user of the original macro accidentally used
+an incorrect function pointer.
+.Pp
+Use of this macro is non-portable; this is part of the implementation
+namespace and should only be used in
+.Nx
+code.
diff -r 8e6eca27366c -r 643e803de5d8 share/man/man3/cdefs.3
--- a/share/man/man3/cdefs.3    Sun Nov 10 14:20:50 2019 +0000
+++ b/share/man/man3/cdefs.3    Sun Nov 10 18:45:09 2019 +0000
@@ -1,4 +1,4 @@
-.\" $NetBSD: cdefs.3,v 1.4 2013/10/27 10:05:15 apb Exp $
+.\" $NetBSD: cdefs.3,v 1.5 2019/11/10 18:45:09 christos Exp $
 .\"
 .\" Copyright (c) 2010 The NetBSD Foundation, Inc.
 .\" All rights reserved.
@@ -27,7 +27,7 @@
 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
 .\" POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd April 8, 2011
+.Dd November 10, 2019
 .Dt CDEFS 3
 .Os
 .Sh NAME
@@ -54,8 +54,15 @@
 .Tn C99 .
 .It
 Macros and definitions specific to compilers, preprocessors, and linkers; see
+.Xr __BIT 3 ,
+.Xr __BITS 3 ,
 .Xr __CONCAT 3 ,
+.Xr __FPTRCAST 3 ,
+.Xr __SHIFTIN 3 ,
+.Xr __SHIFTOUT 3 ,
+.Xr __SHIFTOUT_MASK 3 ,
 .Xr __UNCONST 3 ,
+.Xr __UNVOLATILE 3 ,
 .Xr __USE 3 ,
 .Xr __insn_barrier 3 ,
 and
@@ -89,7 +96,7 @@
  */
 
 #include <sys/cdefs.h>
-__RCSID("$NetBSD: cdefs.3,v 1.4 2013/10/27 10:05:15 apb Exp $");
+__RCSID("$NetBSD: cdefs.3,v 1.5 2019/11/10 18:45:09 christos Exp $");
 .Ed
 .Pp
 It is possible to identify the