Unix/Linux Go Back    


NetBSD 6.1.5 - man page for __pure (netbsd section 3)

Linux & Unix Commands - Search Man Pages
Man Page or Keyword Search:   man
Select Man Page Set:       apropos Keyword Search (sections above)


ATTRIBUTE(3)			   BSD Library Functions Manual 		     ATTRIBUTE(3)

NAME
     attribute -- non-standard GCC attribute extensions

SYNOPSIS
     #include <sys/cdefs.h>

     __dead

     __pure

     __constfunc

     __noinline

     __unused

     __used

     __packed

     __aligned(x);

     __section(section);

     __read_mostly

     __cacheline_aligned

     __predict_true(exp);

     __predict_false(exp);

DESCRIPTION
     The GNU Compiler Collection (GCC) provides many extensions to the standard C language.
     Among these are the so-called attributes.	In NetBSD all attributes are provided in a
     restricted namespace.  The described macros should be preferred instead of using the GCC's
     __attribute__ extension directly.

ATTRIBUTES
     __dead
	  The gcc(1) compiler knows that certain functions such as abort(3) and exit(3) can never
	  return any value.  When such a function is equipped with __dead, certain optimizations
	  are possible.  Obviously a __dead function can never have return type other than void.

     __pure
	  A __pure function is defined to be one that has no effects except the return value,
	  which is assumed to depend only on the function parameters and/or global variables.
	  Any access to parameters and/or global variables must also be read-only.  A function
	  that depends on volatile memory, or other comparable system resource that can change
	  between two consecutive calls, can never be __pure.  Many math(3) functions satisfy the
	  definition of a __pure function, at least in theory.	Other examples include strlen(3)
	  and strcmp(3).

     __constfunc
	  A ``const function'' is a stricter variant of ``pure functions''.  In addition to the
	  restrictions of pure functions, a function declared with __constfunc can never access
	  global variables nor take pointers as parameters.  The return value of these functions
	  must depend only on the passed-by-value parameters.  Note also that a function that
	  calls non-const functions can not be __constfunc.  The canonical example of a const
	  function would be abs(3).  As with pure functions, certain micro-optimizations are pos-
	  sible for functions declared with __constfunc.

     __noinline
	  GCC is known for aggressive function inlining.  Sometimes it is known that inlining is
	  undesirable or that a function will perform incorrectly when inlined.  The __noinline
	  macro expands to a function attribute that prevents GCC for inlining the function,
	  irrespective whether the function was declared with the inline keyword.  The attribute
	  takes precedence over all other compiler options related to inlining.

     __unused
	  In most GCC versions the common -Wall flag enables warnings produced by functions that
	  are defined but unused.  Marking an unused function with the __unused macro inhibits
	  these warnings.

     __used
	  The __used macro expands to an attribute that informs GCC that a static variable or
	  function is to be always retained in the object file even if it is unreferenced.

     __packed
	  The __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 struct or union, all variables
	  therein are also packed.  The __packed macro is often useful when dealing with data
	  that is in a particular static format on the disk, wire, or memory.

     __aligned(x)
	  The __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 x bytes, as opposed to the minimum align-
	  ment requirements dictated by the architecture and the ABI.  Possible use cases
	  include:

		o   Mixing assembly and C code.

		o   Dealing with hardware that may impose alignment requirements greater than the
		    architecture itself.

		o   Using instructions that may impose special alignment requirements.	Typical
		    example would be alignment of frequently used objects along processor cache
		    lines.

	  Note that when used with functions, structures, or structure members, __aligned() can
	  only be used to increase the alignment.  If the macro is however used as part of a
	  typedef, the alignment can both increase and decrease.  Otherwise it is only possible
	  to decrease the alignment for variables and fields by using the __packed macro.  The
	  effectiveness of __aligned() is largely dependent on the linker.  The __alignof__(3)
	  operator can be used to examine the alignment.

     __section(section)
	  The __section() macro expands to an attribute that specifies a particular section to
	  which a variable or function should be placed.  Normally the compiler places the gener-
	  ated objects to sections such as ``data'' or ``text''.  By using __section(), it is
	  possible to override this behavior, perhaps in order to place some variables into par-
	  ticular sections specific to unique hardware.

     __read_mostly
	  The __read_mostly macro uses __section() to place a variable or function into the
	  ``.data.read_mostly'' section of the (kernel) elf(5).  The use of __read_mostly allows
	  infrequently modified data to be grouped together; it is expected that the cachelines
	  of rarely and frequently modified data structures are this way separated.  Candidates
	  for __read_mostly include variables that are initialized once, read very often, and
	  seldom written to.

     __cacheline_aligned
	  The __cacheline_aligned macro behaves like __read_mostly, but the used section is
	  ``.data.cacheline_aligned'' instead.	It also uses __aligned() to set the minimum
	  alignment into a predefined coherency unit.  This should ensure that frequently used
	  data structures are aligned on cacheline boundaries.	Both __cacheline_aligned and
	  __read_mostly are only available for the kernel.

     __predict_true
	  A branch is generally defined to be a conditional execution of a program depending on
	  whether a certain flow control mechanism is altered.	Typical example would be a
	  ``if-then-else'' sequence used in high-level languages or a jump instruction used in
	  machine-level code.  A branch prediction would then be defined as an attempt to guess
	  whether a conditional branch will be taken.

	  The macros __predict_true() and __predict_false() annotate the likelihood of whether a
	  branch will evaluate to true or false.  The rationale is to improve instruction pipe-
	  lining.  Semantically __predict_true expects that the integral expression exp equals 1.

     __predict_false
	  The __predict_false expands to an attribute that instructs the compiler to predict that
	  a given branch will be likely false.	As programmers are notoriously bad at predicting
	  the likely behavior of their code, profiling and empirical evidence should precede the
	  use of __predict_false and __predict_true.

SEE ALSO
     gcc(1), __builtin_object_size(3), cdefs(3), c(7)

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 sparsely and wisely.

BSD					December 19, 2010				      BSD
Unix & Linux Commands & Man Pages : ©2000 - 2018 Unix and Linux Forums


All times are GMT -4. The time now is 03:19 PM.