@item bnd_legacy
@cindex @code{bnd_legacy} function attribute
-The @code{bnd_legacy} attribute on functions is used to inform
-compiler that function should not be instrumented when compiled
-with @option{-fcheck-pointer-bounds} option.
+@cindex Pointer Bounds Checker attributes
+The @code{bnd_legacy} attribute on functions is used to inform the
+compiler that the function should not be instrumented when compiled
+with the @option{-fcheck-pointer-bounds} option.
@item bnd_instrument
@cindex @code{bnd_instrument} function attribute
-The @code{bnd_instrument} attribute on functions is used to inform
-compiler that function should be instrumented when compiled
-with @option{-fchkp-instrument-marked-only} option.
+The @code{bnd_instrument} attribute on functions is used to inform the
+compiler that the function should be instrumented when compiled
+with the @option{-fchkp-instrument-marked-only} option.
@item regparm (@var{number})
@cindex @code{regparm} attribute
@option{-Wno-designated-init} to suppress them.
@item bnd_variable_size
+@cindex @code{bnd_variable_size} attribute
+@cindex Pointer Bounds Checker attributes
When applied to a structure field, this attribute tells Pointer
Bounds Checker that the size of this field should not be computed
-using static type information. It may be used to mark variable
-sized static array fields placed at the end of a structure.
+using static type information. It may be used to mark variably-sized
+static array fields placed at the end of a structure.
@smallexample
struct S
p->data[10] = 0; //Bounds violation
@end smallexample
-By using an attribute for a field we may avoid bound violation
-we most probably do not want to see:
+@noindent
+By using an attribute for the field we may avoid unwanted bound
+violation checks:
@smallexample
struct S
@node Pointer Bounds Checker builtins
@section Pointer Bounds Checker Built-in Functions
+@cindex Pointer Bounds Checker builtins
@findex __builtin___bnd_set_ptr_bounds
@findex __builtin___bnd_narrow_ptr_bounds
@findex __builtin___bnd_copy_ptr_bounds
@findex __builtin___bnd_get_ptr_ubound
GCC provides a set of built-in functions to control Pointer Bounds Checker
-instrumentation. Note that all Pointer Bounds Checker builtins are allowed
-to use even if you compile with Pointer Bounds Checker off. The builtins
-behavior may differ in such case as documented below.
+instrumentation. Note that all Pointer Bounds Checker builtins can be used
+even if you compile with Pointer Bounds Checker off
+(@option{-fno-check-pointer-bounds}).
+The behavior may differ in such case as documented below.
-@deftypefn {Built-in Function} void * __builtin___bnd_set_ptr_bounds (const void * @var{q}, size_t @var{size})
+@deftypefn {Built-in Function} {void *} __builtin___bnd_set_ptr_bounds (const void *@var{q}, size_t @var{size})
This built-in function returns a new pointer with the value of @var{q}, and
associate it with the bounds [@var{q}, @var{q}+@var{size}-1]. With Pointer
-Bounds Checker off built-in function just returns the first argument.
+Bounds Checker off, the built-in function just returns the first argument.
@smallexample
extern void *__wrap_malloc (size_t n)
@end deftypefn
-@deftypefn {Built-in Function} void * __builtin___bnd_narrow_ptr_bounds (const void * @var{p}, const void * @var{q}, size_t @var{size})
+@deftypefn {Built-in Function} {void *} __builtin___bnd_narrow_ptr_bounds (const void *@var{p}, const void *@var{q}, size_t @var{size})
This built-in function returns a new pointer with the value of @var{p}
-and associate it with the narrowed bounds formed by the intersection
-of bounds associated with @var{q} and the [@var{p}, @var{p} + @var{size} - 1].
-With Pointer Bounds Checker off built-in function just returns the first
+and associates it with the narrowed bounds formed by the intersection
+of bounds associated with @var{q} and the bounds
+[@var{p}, @var{p} + @var{size} - 1].
+With Pointer Bounds Checker off, the built-in function just returns the first
argument.
@smallexample
void init_objects (object *objs, size_t size)
@{
size_t i;
- /* Initialize objects one-by-one passing pointers with bounds of an object,
- not the full array of objects. */
+ /* Initialize objects one-by-one passing pointers with bounds of
+ an object, not the full array of objects. */
for (i = 0; i < size; i++)
- init_object (__builtin___bnd_narrow_ptr_bounds (objs + i, objs, sizeof(object)));
+ init_object (__builtin___bnd_narrow_ptr_bounds (objs + i, objs,
+ sizeof(object)));
@}
@end smallexample
@end deftypefn
-@deftypefn {Built-in Function} void * __builtin___bnd_copy_ptr_bounds (const void * @var{q}, const void * @var{r})
+@deftypefn {Built-in Function} {void *} __builtin___bnd_copy_ptr_bounds (const void *@var{q}, const void *@var{r})
This built-in function returns a new pointer with the value of @var{q},
-and associate it with the bounds already associated with pointer @var{r}.
-With Pointer Bounds Checker off built-in function just returns the first
+and associates it with the bounds already associated with pointer @var{r}.
+With Pointer Bounds Checker off, the built-in function just returns the first
argument.
@smallexample
/* Here is a way to get pointer to object's field but
still with the full object's bounds. */
-int *field_ptr = __builtin___bnd_copy_ptr_bounds (&objptr->int_filed, objptr);
+int *field_ptr = __builtin___bnd_copy_ptr_bounds (&objptr->int_field,
+ objptr);
@end smallexample
@end deftypefn
-@deftypefn {Built-in Function} void * __builtin___bnd_init_ptr_bounds (const void * @var{q})
+@deftypefn {Built-in Function} {void *} __builtin___bnd_init_ptr_bounds (const void *@var{q})
This built-in function returns a new pointer with the value of @var{q}, and
-associate it with INIT (allowing full memory access) bounds. With Pointer
-Bounds Checker off built-in function just returns the first argument.
+associates it with INIT (allowing full memory access) bounds. With Pointer
+Bounds Checker off, the built-in function just returns the first argument.
@end deftypefn
-@deftypefn {Built-in Function} void * __builtin___bnd_null_ptr_bounds (const void * @var{q})
+@deftypefn {Built-in Function} {void *} __builtin___bnd_null_ptr_bounds (const void *@var{q})
This built-in function returns a new pointer with the value of @var{q}, and
-associate it with NULL (allowing no memory access) bounds. With Pointer
-Bounds Checker off built-in function just returns the first argument.
+associates it with NULL (allowing no memory access) bounds. With Pointer
+Bounds Checker off, the built-in function just returns the first argument.
@end deftypefn
-@deftypefn {Built-in Function} void __builtin___bnd_store_ptr_bounds (const void ** @var{ptr_addr}, const void * @var{ptr_val})
+@deftypefn {Built-in Function} void __builtin___bnd_store_ptr_bounds (const void **@var{ptr_addr}, const void *@var{ptr_val})
This built-in function stores the bounds associated with pointer @var{ptr_val}
and location @var{ptr_addr} into Bounds Table. This can be useful to propagate
bounds from legacy code without touching the associated pointer's memory when
-pointers were copied as integers. With Pointer Bounds Checker off built-in
+pointers are copied as integers. With Pointer Bounds Checker off, the built-in
function call is ignored.
@end deftypefn
-@deftypefn {Built-in Function} void __builtin___bnd_chk_ptr_lbounds (const void * @var{q})
+@deftypefn {Built-in Function} void __builtin___bnd_chk_ptr_lbounds (const void *@var{q})
This built-in function checks if the pointer @var{q} is within the lower
-bound of its associated bounds. With Pointer Bounds Checker off built-in
+bound of its associated bounds. With Pointer Bounds Checker off, the built-in
function call is ignored.
@smallexample
@end deftypefn
-@deftypefn {Built-in Function} void __builtin___bnd_chk_ptr_ubounds (const void * @var{q})
+@deftypefn {Built-in Function} void __builtin___bnd_chk_ptr_ubounds (const void *@var{q})
This built-in function checks if the pointer @var{q} is within the upper
-bound of its associated bounds. With Pointer Bounds Checker off built-in
+bound of its associated bounds. With Pointer Bounds Checker off, the built-in
function call is ignored.
@end deftypefn
-@deftypefn {Built-in Function} void __builtin___bnd_chk_ptr_bounds (const void * @var{q}, size_t @var{size})
+@deftypefn {Built-in Function} void __builtin___bnd_chk_ptr_bounds (const void *@var{q}, size_t @var{size})
This built-in function checks if [@var{q}, @var{q} + @var{size} - 1] is within
the lower and upper bounds associated with @var{q}. With Pointer Bounds Checker
-off built-in function call is ignored.
+off, the built-in function call is ignored.
@smallexample
extern void *__wrap_memcpy (void *dst, const void *src, size_t n)
@end deftypefn
-@deftypefn {Built-in Function} const void * __builtin___bnd_get_ptr_lbound (const void * @var{q})
+@deftypefn {Built-in Function} {const void *} __builtin___bnd_get_ptr_lbound (const void *@var{q})
-This built-in function returns the lower bound (which is a pointer) associated
-with the pointer @var{q}. This is at least useful for debugging using printf.
-With Pointer Bounds Checker off built-in function returns 0.
+This built-in function returns the lower bound associated
+with the pointer @var{q}, as a pointer value.
+This is useful for debugging using @code{printf}.
+With Pointer Bounds Checker off, the built-in function returns 0.
@smallexample
void *lb = __builtin___bnd_get_ptr_lbound (q);
@end deftypefn
-@deftypefn {Built-in Function} const void * __builtin___bnd_get_ptr_ubound (const void * @var{q})
+@deftypefn {Built-in Function} {const void *} __builtin___bnd_get_ptr_ubound (const void *@var{q})
This built-in function returns the upper bound (which is a pointer) associated
-with the pointer @var{q}. With Pointer Bounds Checker off built-in function
-returns -1.
+with the pointer @var{q}. With Pointer Bounds Checker off,
+the built-in function returns -1.
@end deftypefn
@item -fcheck-pointer-bounds
@opindex fcheck-pointer-bounds
@opindex fno-check-pointer-bounds
+@cindex Pointer Bounds Checker options
Enable Pointer Bounds Checker instrumentation. Each memory reference
-is instrumented with checks of pointer used for memory access against
-bounds associated with that pointer. Generated instrumentation may
-be controlled by various @option{-fchkp-*} options. Currently there
-is only Intel MPX based implementation available, thus i386 target
-and @option{-mmpx} are required. MPX based instrumentation requires
-a runtime library to enable MPX in a hardware and handle bounds
+is instrumented with checks of the pointer used for memory access against
+bounds associated with that pointer.
+
+Currently there
+is only an implementation for Intel MPX available, thus x86 target
+and @option{-mmpx} are required to enable this feature.
+MPX-based instrumentation requires
+a runtime library to enable MPX in hardware and handle bounds
violation signals. By default when @option{-fcheck-pointer-bounds}
and @option{-mmpx} options are used to link a program, the GCC driver
-links against @option{libmpx} runtime library. MPX based instrumentation
-may be used for a debugging and also it may be included into a release
-version to increase program security. Depending on usage you may
-put different requirements to runtime library. Current version
- of MPX runtime library is more oriented to be used as a debugging
+links against the @file{libmpx} runtime library. MPX-based instrumentation
+may be used for debugging and also may be included in production code
+to increase program security. Depending on usage, you may
+have different requirements for the runtime library. The current version
+of the MPX runtime library is more oriented for use as a debugging
tool. MPX runtime library usage implies @option{-lpthread}. See
also @option{-static-libmpx}. The runtime library behavior can be
influenced using various @env{CHKP_RT_*} environment variables. See
@uref{https://gcc.gnu.org/wiki/Intel%20MPX%20support%20in%20the%20GCC%20compiler}
for more details.
+Generated instrumentation may be controlled by various
+@option{-fchkp-*} options and by the @code{bnd_variable_size}
+structure field attribute (@pxref{Type Attributes}) and
+@code{bnd_legacy}, and @code{bnd_instrument} function attributes
+(@pxref{Function Attributes}). GCC also provides a number of built-in
+functions for controlling the Pointer Bounds Checker. @xref{Pointer
+Bounds Checker builtins}, for more information.
+
@item -fchkp-check-incomplete-type
@opindex fchkp-check-incomplete-type
@opindex fno-chkp-check-incomplete-type
Generate pointer bounds checks for variables with incomplete type.
-Enabled by default
+Enabled by default.
@item -fchkp-narrow-bounds
@opindex fchkp-narrow-bounds
@item -fchkp-first-field-has-own-bounds
@opindex fchkp-first-field-has-own-bounds
@opindex fno-chkp-first-field-has-own-bounds
-Forces Pointer Bounds Checker to use narrowed bounds for address of the
-first field in the structure. By default pointer to the first field has
-the same bounds as pointer to the whole structure.
+Forces Pointer Bounds Checker to use narrowed bounds for the address of the
+first field in the structure. By default a pointer to the first field has
+the same bounds as a pointer to the whole structure.
@item -fchkp-narrow-to-innermost-array
@opindex fchkp-narrow-to-innermost-array
@opindex fno-chkp-narrow-to-innermost-array
Forces Pointer Bounds Checker to use bounds of the innermost arrays in
-case of nested static arryas access. By default it is disabled and
+case of nested static array access. By default this option is disabled and
bounds of the outermost array are used.
@item -fchkp-optimize
@item -fchkp-use-fast-string-functions
@opindex fchkp-use-fast-string-functions
@opindex fno-chkp-use-fast-string-functions
-Allow to use @code{*_nobnd} versions of string functions (not copying bounds)
+Enables use of @code{*_nobnd} versions of string functions (not copying bounds)
by Pointer Bounds Checker. Disabled by default.
@item -fchkp-use-nochk-string-functions
@opindex fchkp-use-nochk-string-functions
@opindex fno-chkp-use-nochk-string-functions
-Allow to use @code{*_nochk} versions of string functions (not checking bounds)
+Enables use of @code{*_nochk} versions of string functions (not checking bounds)
by Pointer Bounds Checker. Disabled by default.
@item -fchkp-use-static-bounds
@item -fchkp-use-static-const-bounds
@opindex fchkp-use-static-const-bounds
@opindex fno-chkp-use-static-const-bounds
-Use statically initialized bounds for constant bounds instead of
-generating them each time it is required. By default enabled when
+Use statically-initialized bounds for constant bounds instead of
+generating them each time they are required. By default enabled when
@option{-fchkp-use-static-bounds} is enabled.
@item -fchkp-treat-zero-dynamic-size-as-infinite
@opindex fchkp-treat-zero-dynamic-size-as-infinite
@opindex fno-chkp-treat-zero-dynamic-size-as-infinite
-With this option zero size obtained dynamically for objects with
-incomplete type will be treated as infinite by Pointer Bounds
-Checker. It may be helpful if program is linked with a library
+With this option, objects with incomplete type whose
+dynamically-obtained size is zero are treated as having infinite size
+instead by Pointer Bounds
+Checker. This option may be helpful if a program is linked with a library
missing size information for some symbols. Disabled by default.
@item -fchkp-check-read
@opindex fchkp-instrument-marked-only
@opindex fno-chkp-instrument-marked-only
Instructs Pointer Bounds Checker to instrument only functions
-marked with @code{bnd_instrument} attribute. Disabled by default.
+marked with the @code{bnd_instrument} attribute
+(@pxref{Function Attributes}). Disabled by default.
@item -fchkp-use-wrappers
@opindex fchkp-use-wrappers
@opindex fno-chkp-use-wrappers
-Allows Pointer Bounds Checker to replace calls to built-in function
-with calls to wrapper functions. When the @option{-fchkp-use-wrappers}
+Allows Pointer Bounds Checker to replace calls to built-in functions
+with calls to wrapper functions. When @option{-fchkp-use-wrappers}
is used to link a program, the GCC driver automatically links
-agains @option{libmpxwrappers}. See also @option{-static-libmpxwrappers}.
+against @file{libmpxwrappers}. See also @option{-static-libmpxwrappers}.
Enabled by default.
@item -fdump-final-insns@r{[}=@var{file}@r{]}
@item -static-libmpx
@opindex static-libmpx
-When @option{-fcheck-pointer bounds} and @option{-mmpx} options are
+When the @option{-fcheck-pointer bounds} and @option{-mmpx} options are
used to link a program, the GCC driver automatically links against
-@option{libmpx}. If @file{libmpx} is available as a shared library,
+@file{libmpx}. If @file{libmpx} is available as a shared library,
and the @option{-static} option is not used, then this links against
the shared version of @file{libmpx}. The @option{-static-libmpx}
option directs the GCC driver to link @file{libmpx} statically,
@item -static-libmpxwrappers
@opindex static-libmpxwrappers
-When @option{-fcheck-pointer bounds}, @option{-mmpx} options are used and
-@option{-fno-chkp-use-wrappers} option is not used to link a program, the
-GCC driver automatically links against @option{libmpxwrappers}. If
+When the @option{-fcheck-pointer bounds} and @option{-mmpx} options are used
+to link a program without also using @option{-fno-chkp-use-wrappers}, the
+GCC driver automatically links against @file{libmpxwrappers}. If
@file{libmpxwrappers} is available as a shared library, and the
@option{-static} option is not used, then this links against the shared
version of @file{libmpxwrappers}. The @option{-static-libmpxwrappers}
projects / gcc.git / commitdiff