Module Name: src
Committed By: jruoho
Date: Tue Mar 2 06:20:03 UTC 2010
Modified Files:
src/share/man/man3: __UNCONST.3
Log Message:
As per suggestions from mrg@, improve the lead paragraph and stress that
these macros are not recommended. Also remove the example as it feels a
little frivolous and takes too much space.
To generate a diff of this commit:
cvs rdiff -u -r1.2 -r1.3 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/__UNCONST.3
diff -u src/share/man/man3/__UNCONST.3:1.2 src/share/man/man3/__UNCONST.3:1.3
--- src/share/man/man3/__UNCONST.3:1.2 Mon Mar 1 15:30:47 2010
+++ src/share/man/man3/__UNCONST.3 Tue Mar 2 06:20:03 2010
@@ -1,4 +1,4 @@
-.\" $NetBSD: __UNCONST.3,v 1.2 2010/03/01 15:30:47 wiz Exp $
+.\" $NetBSD: __UNCONST.3,v 1.3 2010/03/02 06:20:03 jruoho Exp $
.\"
.\" Copyright (c) 2010 The NetBSD Foundation, Inc.
.\" All rights reserved.
@@ -43,40 +43,31 @@
The
.Fn __UNCONST
macro can be used to omit warnings produced by certain compilers when
-a pointer declared with the
+operating with pointers declared with the
.Em const
-type qualifier is being passed to a function without such qualifier.
+type qualifier in a context without such qualifier.
+Examples include passing a pointer declared with the
+.Em const
+qualifier to a function without such qualifier,
+and variable assignment from a
+.Em const
+pointer to a non-const pointer.
In the same vein, the
.Fn __UNVOLATILE
-macro can be used to omit warnings related to the
+macro can be used to exclude warnings related to the
.Em volatile
type qualifier.
.Sh IMPLEMENTATION NOTES
-Both macros are implemented by explicitly using
+These 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 SEE ALSO
.Xr cc 1
.Sh CAVEATS
-Both macros should be used with care because these can hide valid errors.
+As both macros may hide valid errors, their usage is not recommended
+unless there is a well-thought reason for a cast.
A typical use case for
.Fn __UNCONST
involve an
@@ -85,5 +76,7 @@
even if it would be appropriate.
Valid use cases of
.Fn __UNVOLATILE
-include passing a volatile pointer to
+include passing a
+.Em volatile
+pointer to
.Xr memset 3 .
