Module Name: src
Committed By: christos
Date: Sun Nov 10 18:45:09 UTC 2019
Modified Files:
src/share/man/man3: Makefile cdefs.3
Added Files:
src/share/man/man3: __FPTRCAST.3
Log Message:
Document __FPTRCAST
XXX: more macros need documentation (__CAST etc.)
To generate a diff of this commit:
cvs rdiff -u -r1.88 -r1.89 src/share/man/man3/Makefile
cvs rdiff -u -r0 -r1.1 src/share/man/man3/__FPTRCAST.3
cvs rdiff -u -r1.4 -r1.5 src/share/man/man3/cdefs.3
Please note that diffs are not public domain; they are subject to the
copyright notices on the relevant files.
Modified files:
Index: src/share/man/man3/Makefile
diff -u src/share/man/man3/Makefile:1.88 src/share/man/man3/Makefile:1.89
--- src/share/man/man3/Makefile:1.88 Wed Nov 27 11:30:12 2013
+++ src/share/man/man3/Makefile Sun Nov 10 13:45:09 2019
@@ -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 \
Index: src/share/man/man3/cdefs.3
diff -u src/share/man/man3/cdefs.3:1.4 src/share/man/man3/cdefs.3:1.5
--- src/share/man/man3/cdefs.3:1.4 Sun Oct 27 06:05:15 2013
+++ src/share/man/man3/cdefs.3 Sun Nov 10 13:45:09 2019
@@ -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 @@ type qualifier from
.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 @@ included as the first thing right after
*/
#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
Added files:
Index: src/share/man/man3/__FPTRCAST.3
diff -u /dev/null src/share/man/man3/__FPTRCAST.3:1.1
--- /dev/null Sun Nov 10 13:45:09 2019
+++ src/share/man/man3/__FPTRCAST.3 Sun Nov 10 13:45:09 2019
@@ -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.
