Start to document the GNU C attributes. For now, only __packed, __aligned,
and __section are documented, but I will keep extending this.
This commit is contained in:
jruoho
parent
7d94efc224
commit
084bbf58ac
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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 @@ USETBL= # used by queue.3
|
|||
|
||||
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 \
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
Loading…
Reference in New Issue