Module Name: src
Committed By: jruoho
Date: Thu Dec 16 08:35:36 UTC 2010
Modified Files:
src/distrib/sets/lists/comp: mi
src/share/man/man3: Makefile
Added Files:
src/share/man/man3: attribute.3
Log Message:
Start to document the GNU C attributes. For now, only __packed, __aligned,
and __section are documented, but I will keep extending this.
To generate a diff of this commit:
cvs rdiff -u -r1.1545 -r1.1546 src/distrib/sets/lists/comp/mi
cvs rdiff -u -r1.58 -r1.59 src/share/man/man3/Makefile
cvs rdiff -u -r0 -r1.1 src/share/man/man3/attribute.3
Please note that diffs are not public domain; they are subject to the
copyright notices on the relevant files.
Modified files:
Index: src/distrib/sets/lists/comp/mi
diff -u src/distrib/sets/lists/comp/mi:1.1545 src/distrib/sets/lists/comp/mi:1.1546
--- src/distrib/sets/lists/comp/mi:1.1545 Wed Dec 15 18:39:28 2010
+++ src/distrib/sets/lists/comp/mi Thu Dec 16 08:35:36 2010
@@ -1,4 +1,4 @@
-# $NetBSD: mi,v 1.1545 2010/12/15 18:39:28 pooka Exp $
+# $NetBSD: mi,v 1.1546 2010/12/16 08:35:36 jruoho Exp $
#
# Note: don't delete entries from here - mark them as "obsolete" instead.
#
@@ -4903,8 +4903,11 @@
./usr/share/man/cat3/__STRING.0 comp-c-catman .cat
./usr/share/man/cat3/__UNCONST.0 comp-c-catman .cat
./usr/share/man/cat3/__UNVOLATILE.0 comp-c-catman .cat
+./usr/share/man/cat3/__aligned.0 comp-c-catman .cat
./usr/share/man/cat3/__arraycount.0 comp-c-catman .cat
./usr/share/man/cat3/__builtin_object_size.0 comp-c-catman .cat
+./usr/share/man/cat3/__packed.0 comp-c-catman .cat
+./usr/share/man/cat3/__section.0 comp-c-catman .cat
./usr/share/man/cat3/__svc_getcallercreds.0 comp-c-catman .cat
./usr/share/man/cat3/_longjmp.0 comp-c-catman .cat
./usr/share/man/cat3/_lwp_makecontext.0 comp-c-catman .cat
@@ -5215,6 +5218,7 @@
./usr/share/man/cat3/attr_off.0 comp-c-catman .cat
./usr/share/man/cat3/attr_on.0 comp-c-catman .cat
./usr/share/man/cat3/attr_set.0 comp-c-catman .cat
+./usr/share/man/cat3/attribute.0 comp-c-catman .cat
./usr/share/man/cat3/attroff.0 comp-c-catman .cat
./usr/share/man/cat3/attron.0 comp-c-catman .cat
./usr/share/man/cat3/attrset.0 comp-c-catman .cat
@@ -10963,8 +10967,11 @@
./usr/share/man/html3/__STRING.html comp-c-htmlman html
./usr/share/man/html3/__UNCONST.html comp-c-htmlman html
./usr/share/man/html3/__UNVOLATILE.html comp-c-htmlman html
+./usr/share/man/html3/__aligned.html comp-c-htmlman html
./usr/share/man/html3/__arraycount.html comp-c-htmlman html
./usr/share/man/html3/__builtin_object_size.html comp-c-htmlman html
+./usr/share/man/html3/__packed.html comp-c-htmlman html
+./usr/share/man/html3/__section.html comp-c-htmlman html
./usr/share/man/html3/__svc_getcallercreds.html comp-c-htmlman html
./usr/share/man/html3/_longjmp.html comp-c-htmlman html
./usr/share/man/html3/_lwp_makecontext.html comp-c-htmlman html
@@ -11275,6 +11282,7 @@
./usr/share/man/html3/attr_off.html comp-c-htmlman html
./usr/share/man/html3/attr_on.html comp-c-htmlman html
./usr/share/man/html3/attr_set.html comp-c-htmlman html
+./usr/share/man/html3/attribute.html comp-c-htmlman html
./usr/share/man/html3/attroff.html comp-c-htmlman html
./usr/share/man/html3/attron.html comp-c-htmlman html
./usr/share/man/html3/attrset.html comp-c-htmlman html
@@ -16823,8 +16831,11 @@
./usr/share/man/man3/__STRING.3 comp-c-man .man
./usr/share/man/man3/__UNCONST.3 comp-c-man .man
./usr/share/man/man3/__UNVOLATILE.3 comp-c-man .man
+./usr/share/man/man3/__aligned.3 comp-c-man .man
./usr/share/man/man3/__arraycount.3 comp-c-man .man
./usr/share/man/man3/__builtin_object_size.3 comp-c-man .man
+./usr/share/man/man3/__packed.3 comp-c-man .man
+./usr/share/man/man3/__section.3 comp-c-man .man
./usr/share/man/man3/__svc_getcallercreds.3 comp-c-man .man
./usr/share/man/man3/_longjmp.3 comp-c-man .man
./usr/share/man/man3/_lwp_makecontext.3 comp-c-man .man
@@ -17135,6 +17146,7 @@
./usr/share/man/man3/attr_off.3 comp-c-man .man
./usr/share/man/man3/attr_on.3 comp-c-man .man
./usr/share/man/man3/attr_set.3 comp-c-man .man
+./usr/share/man/man3/attribute.3 comp-c-man .man
./usr/share/man/man3/attroff.3 comp-c-man .man
./usr/share/man/man3/attron.3 comp-c-man .man
./usr/share/man/man3/attrset.3 comp-c-man .man
Index: src/share/man/man3/Makefile
diff -u src/share/man/man3/Makefile:1.58 src/share/man/man3/Makefile:1.59
--- src/share/man/man3/Makefile:1.58 Tue Dec 14 17:09:27 2010
+++ src/share/man/man3/Makefile Thu Dec 16 08:35:35 2010
@@ -1,8 +1,8 @@
-# $NetBSD: Makefile,v 1.58 2010/12/14 17:09:27 jruoho Exp $
+# $NetBSD: Makefile,v 1.59 2010/12/16 08:35:35 jruoho Exp $
# @(#)Makefile 8.2 (Berkeley) 12/13/93
MAN= _DIAGASSERT.3 __CONCAT.3 __UNCONST.3 CMSG_DATA.3 \
- __arraycount.3 assert.3 bits.3 bitstring.3 dirent.3 \
+ __arraycount.3 assert.3 attribute.3 bits.3 bitstring.3 dirent.3 \
dlfcn.3 dl_iterate_phdr.3 end.3 \
fast_divide32.3 ffs32.3 gcq.3 \
ilog2.3 intro.3 inttypes.3 iso646.3 \
@@ -14,6 +14,9 @@
MLINKS+=__CONCAT.3 __STRING.3
MLINKS+=__UNCONST.3 __UNVOLATILE.3
+MLINKS+=attribute.3 __packed.3 \
+ attribute.3 __aligned.3 \
+ attribute.3 __section.3
MLINKS+=bitstring.3 bit_alloc.3 \
bitstring.3 bit_clear.3 \
bitstring.3 bit_decl.3 \
Added files:
Index: src/share/man/man3/attribute.3
diff -u /dev/null src/share/man/man3/attribute.3:1.1
--- /dev/null Thu Dec 16 08:35:36 2010
+++ src/share/man/man3/attribute.3 Thu Dec 16 08:35:35 2010
@@ -0,0 +1,137 @@
+.\" $NetBSD: attribute.3,v 1.1 2010/12/16 08:35:35 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 December 16, 2010
+.Dt ATTRIBUTE 3
+.Os
+.Sh NAME
+.Nm attribute
+.Nd non-standard GCC extensions
+.Sh SYNOPSIS
+.In sys/cdefs.h
+.Pp
+.Ic __packed
+.Pp
+.Fn __aligned "x"
+.Fn __section "section"
+.Sh DESCRIPTION
+The
+.Tn GNU
+Compiler Collection
+.Pq Tn GCC
+provides many extensions to the standard C language.
+Among these are the so-called attributes.
+In
+.Nx
+all attributes are provided in a restricted namespace.
+The described macros should be preferred instead of using the
+.Tn GCC's
+.Em __attribute__
+extension directly.
+.Pp
+.Sh FUNCTIONS
+.Bl -tag -width abc
+.It Ic __packed
+The
+.Ic __packed
+macro expands to an attribute that forces a variable or
+structure field to have the smallest possible alignment,
+potentially disregarding architecture specific alignment requirements.
+The smallest possible alignment is effectively one byte
+for variables and one bit for fields.
+If specified on a
+.Vt struct
+or
+.Vt union ,
+all variables therein are also packed.
+.It Fn __aligned "x"
+The
+.Fn __aligned
+macro expands to an attribute that specifies the minimum alignment
+in bytes for a variable, structure field, or function.
+In other words, the specified object should have an alignment of at least
+.Fa x
+bytes, as opposed to the minimum alignment requirements dictated
+by the architecture and the
+.Tn ABI .
+Possible use cases include:
+.Bl -bullet -offset indent
+.It
+Mixing assembly and C code.
+.It
+Dealing with hardware that may impose alignment requirements
+greater than the architecture itself.
+.It
+Using instructions that may impose special alignment requirements.
+Typical example would be alignment of frequently used objects along
+processor cache lines.
+.El
+.Pp
+Note that when used with functions, structures, or structure members,
+.Fn __aligned
+can only be used to increase the alignment.
+It is however possible to decrease the alignment
+for variables and fields by using the
+.Ic __packed
+macro.
+If
+.Fn __aligned
+is used as part of a
+.Vt typedef ,
+the alignment can both increase and decrease.
+The effectiveness of
+.Fn __aligned
+is largely dependent on the linker.
+.It Fn __section "section"
+The
+.Fn __section
+macro expands to an attribute that specifies a particular
+.Fa section
+to which a variable or function should be placed.
+Normally the compiler places the generated objects to sections such as
+.Dq data
+or
+.Dq text .
+By using
+.Fn __section ,
+it is possible to override this behavior, perhaps in order to place
+some variables into particular sections specific to unique hardware.
+Generally the use cases of
+.Fn __section
+are very limited.
+.El
+.Sh SEE ALSO
+.Xr gcc 1 ,
+.Xr c 7
+.Sh CAVEATS
+It goes without saying that portable applications
+should steer clear from non-standard extensions specific
+to any given compiler.
+Even when portability is not a concern,
+use these macros wisely.
