Module Name: src Committed By: jruoho Date: Mon Mar 1 13:44:10 UTC 2010
Modified Files: src/share/man/man3: Makefile Added Files: src/share/man/man3: __UNCONST.3 Log Message: Document __UNCONST and __UNVOLATILE. XXX: If there is anything to add or correct, please do so! To generate a diff of this commit: cvs rdiff -u -r1.36 -r1.37 src/share/man/man3/Makefile cvs rdiff -u -r0 -r1.1 src/share/man/man3/__UNCONST.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.36 src/share/man/man3/Makefile:1.37 --- src/share/man/man3/Makefile:1.36 Sat Feb 27 22:04:38 2010 +++ src/share/man/man3/Makefile Mon Mar 1 13:44:09 2010 @@ -1,13 +1,14 @@ -# $NetBSD: Makefile,v 1.36 2010/02/27 22:04:38 wiz Exp $ +# $NetBSD: Makefile,v 1.37 2010/03/01 13:44:09 jruoho Exp $ # @(#)Makefile 8.2 (Berkeley) 12/13/93 -MAN= _DIAGASSERT.3 CMSG_DATA.3 \ +MAN= _DIAGASSERT.3 __UNCONST.3 CMSG_DATA.3 \ assert.3 bits.3 bitstring.3 dlfcn.3 end.3 \ gcq.3 intro.3 offsetof.3 queue.3 stdarg.3 sysexits.3 \ timeradd.3 tree.3 varargs.3 USETBL= # used by queue.3 +MLINKS+=__UNCONST.3 __UNVOLATILE.3 MLINKS+=bitstring.3 bit_alloc.3 \ bitstring.3 bit_clear.3 \ bitstring.3 bit_decl.3 \ Added files: Index: src/share/man/man3/__UNCONST.3 diff -u /dev/null src/share/man/man3/__UNCONST.3:1.1 --- /dev/null Mon Mar 1 13:44:10 2010 +++ src/share/man/man3/__UNCONST.3 Mon Mar 1 13:44:09 2010 @@ -0,0 +1,90 @@ +.\" $NetBSD: __UNCONST.3,v 1.1 2010/03/01 13:44:09 jruoho Exp $ +.\" +.\" Copyright (c) 2010 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Jukka Ruohonen. +.\" +.\" 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 February 28, 2010 +.Os +.Dt __UNCONST 3 +.Sh NAME +.Nm __UNCONST +.Nd compile time cast-away macro +.Sh SYNOPSIS +.In sys/cdefs.h +.Ft void +.Fn __UNCONST x +.Ft void +.Fn __UNVOLATILE x +.Sh DESCRIPTION +The +.Fn __UNCONST +macro can be used to omit warnings produced by certain compilers when +a pointer declared with the +.Em const +type qualifier is being passed to a function without such qualifier. +In the same vein, the +.Fn __UNVOLATILE +macro can be used to omit warnings related to the +.Em volatile +type qualifier. +.Pp +.Sh IMPLEMENTATION NOTES +Both macros are implemented by explicitly using +.Em unsigned long +instead of +.Em intptr_t , +a signed type guaranteed to hold a pointer. +.Sh EXAMPLES +The following example demonstrates a possible usage of +.Fn __UNCONST : +.Bd -literal -offset indent +const char *str = "/dev/null"; + +api_function(__UNCONST(str)); + +\&... + +static void +api_function(char *str) +{ + \&... + +.Ed +.Sh CAVEATS +Both macros should be used with care because these can hide valid errors. +A typical use case for +.Fn __UNCONST +involve an +.Tn API +that does not follow the so-called ``const correctness'' +even if it would be appropriate. +Valid use cases of +.Fn __UNVOLATILE +include passing a volatile pointer to +.Xr memset 3 . +.Sh SEE ALSO +.Xr cc 1