| <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> |
| <html> |
| <!-- Copyright (C) 1988-2015 Free Software Foundation, Inc. |
| |
| Permission is granted to copy, distribute and/or modify this document |
| under the terms of the GNU Free Documentation License, Version 1.3 or |
| any later version published by the Free Software Foundation; with the |
| Invariant Sections being "Funding Free Software", the Front-Cover |
| Texts being (a) (see below), and with the Back-Cover Texts being (b) |
| (see below). A copy of the license is included in the section entitled |
| "GNU Free Documentation License". |
| |
| (a) The FSF's Front-Cover Text is: |
| |
| A GNU Manual |
| |
| (b) The FSF's Back-Cover Text is: |
| |
| You have freedom to copy and modify this GNU Manual, like GNU |
| software. Copies published by the Free Software Foundation raise |
| funds for GNU development. --> |
| <!-- Created by GNU Texinfo 5.2, http://www.gnu.org/software/texinfo/ --> |
| <head> |
| <title>Using the GNU Compiler Collection (GCC): Pointer Bounds Checker builtins</title> |
| |
| <meta name="description" content="Using the GNU Compiler Collection (GCC): Pointer Bounds Checker builtins"> |
| <meta name="keywords" content="Using the GNU Compiler Collection (GCC): Pointer Bounds Checker builtins"> |
| <meta name="resource-type" content="document"> |
| <meta name="distribution" content="global"> |
| <meta name="Generator" content="makeinfo"> |
| <meta http-equiv="Content-Type" content="text/html; charset=utf-8"> |
| <link href="index.html#Top" rel="start" title="Top"> |
| <link href="Option-Index.html#Option-Index" rel="index" title="Option Index"> |
| <link href="index.html#SEC_Contents" rel="contents" title="Table of Contents"> |
| <link href="C-Extensions.html#C-Extensions" rel="up" title="C Extensions"> |
| <link href="Cilk-Plus-Builtins.html#Cilk-Plus-Builtins" rel="next" title="Cilk Plus Builtins"> |
| <link href="Object-Size-Checking.html#Object-Size-Checking" rel="prev" title="Object Size Checking"> |
| <style type="text/css"> |
| <!-- |
| a.summary-letter {text-decoration: none} |
| blockquote.smallquotation {font-size: smaller} |
| div.display {margin-left: 3.2em} |
| div.example {margin-left: 3.2em} |
| div.indentedblock {margin-left: 3.2em} |
| div.lisp {margin-left: 3.2em} |
| div.smalldisplay {margin-left: 3.2em} |
| div.smallexample {margin-left: 3.2em} |
| div.smallindentedblock {margin-left: 3.2em; font-size: smaller} |
| div.smalllisp {margin-left: 3.2em} |
| kbd {font-style:oblique} |
| pre.display {font-family: inherit} |
| pre.format {font-family: inherit} |
| pre.menu-comment {font-family: serif} |
| pre.menu-preformatted {font-family: serif} |
| pre.smalldisplay {font-family: inherit; font-size: smaller} |
| pre.smallexample {font-size: smaller} |
| pre.smallformat {font-family: inherit; font-size: smaller} |
| pre.smalllisp {font-size: smaller} |
| span.nocodebreak {white-space:nowrap} |
| span.nolinebreak {white-space:nowrap} |
| span.roman {font-family:serif; font-weight:normal} |
| span.sansserif {font-family:sans-serif; font-weight:normal} |
| ul.no-bullet {list-style: none} |
| --> |
| </style> |
| |
| |
| </head> |
| |
| <body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000"> |
| <a name="Pointer-Bounds-Checker-builtins"></a> |
| <div class="header"> |
| <p> |
| Next: <a href="Cilk-Plus-Builtins.html#Cilk-Plus-Builtins" accesskey="n" rel="next">Cilk Plus Builtins</a>, Previous: <a href="Object-Size-Checking.html#Object-Size-Checking" accesskey="p" rel="prev">Object Size Checking</a>, Up: <a href="C-Extensions.html#C-Extensions" accesskey="u" rel="up">C Extensions</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Option-Index.html#Option-Index" title="Index" rel="index">Index</a>]</p> |
| </div> |
| <hr> |
| <a name="Pointer-Bounds-Checker-Built_002din-Functions"></a> |
| <h3 class="section">6.55 Pointer Bounds Checker Built-in Functions</h3> |
| <a name="index-Pointer-Bounds-Checker-builtins"></a> |
| <a name="index-_005f_005fbuiltin_005f_005f_005fbnd_005fset_005fptr_005fbounds"></a> |
| <a name="index-_005f_005fbuiltin_005f_005f_005fbnd_005fnarrow_005fptr_005fbounds"></a> |
| <a name="index-_005f_005fbuiltin_005f_005f_005fbnd_005fcopy_005fptr_005fbounds"></a> |
| <a name="index-_005f_005fbuiltin_005f_005f_005fbnd_005finit_005fptr_005fbounds"></a> |
| <a name="index-_005f_005fbuiltin_005f_005f_005fbnd_005fnull_005fptr_005fbounds"></a> |
| <a name="index-_005f_005fbuiltin_005f_005f_005fbnd_005fstore_005fptr_005fbounds"></a> |
| <a name="index-_005f_005fbuiltin_005f_005f_005fbnd_005fchk_005fptr_005flbounds"></a> |
| <a name="index-_005f_005fbuiltin_005f_005f_005fbnd_005fchk_005fptr_005fubounds"></a> |
| <a name="index-_005f_005fbuiltin_005f_005f_005fbnd_005fchk_005fptr_005fbounds"></a> |
| <a name="index-_005f_005fbuiltin_005f_005f_005fbnd_005fget_005fptr_005flbound"></a> |
| <a name="index-_005f_005fbuiltin_005f_005f_005fbnd_005fget_005fptr_005fubound"></a> |
| |
| <p>GCC provides a set of built-in functions to control Pointer Bounds Checker |
| instrumentation. Note that all Pointer Bounds Checker builtins can be used |
| even if you compile with Pointer Bounds Checker off |
| (<samp>-fno-check-pointer-bounds</samp>). |
| The behavior may differ in such case as documented below. |
| </p> |
| <dl> |
| <dt><a name="index-_005f_005fbuiltin_005f_005f_005fbnd_005fset_005fptr_005fbounds-1"></a>Built-in Function: <em>void *</em> <strong>__builtin___bnd_set_ptr_bounds</strong> <em>(const void *<var>q</var>, size_t <var>size</var>)</em></dt> |
| <dd> |
| <p>This built-in function returns a new pointer with the value of <var>q</var>, and |
| associate it with the bounds [<var>q</var>, <var>q</var>+<var>size</var>-1]. With Pointer |
| Bounds Checker off, the built-in function just returns the first argument. |
| </p> |
| <div class="smallexample"> |
| <pre class="smallexample">extern void *__wrap_malloc (size_t n) |
| { |
| void *p = (void *)__real_malloc (n); |
| if (!p) return __builtin___bnd_null_ptr_bounds (p); |
| return __builtin___bnd_set_ptr_bounds (p, n); |
| } |
| </pre></div> |
| |
| </dd></dl> |
| |
| <dl> |
| <dt><a name="index-_005f_005fbuiltin_005f_005f_005fbnd_005fnarrow_005fptr_005fbounds-1"></a>Built-in Function: <em>void *</em> <strong>__builtin___bnd_narrow_ptr_bounds</strong> <em>(const void *<var>p</var>, const void *<var>q</var>, size_t <var>size</var>)</em></dt> |
| <dd> |
| <p>This built-in function returns a new pointer with the value of <var>p</var> |
| and associates it with the narrowed bounds formed by the intersection |
| of bounds associated with <var>q</var> and the bounds |
| [<var>p</var>, <var>p</var> + <var>size</var> - 1]. |
| With Pointer Bounds Checker off, the built-in function just returns the first |
| argument. |
| </p> |
| <div class="smallexample"> |
| <pre class="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. */ |
| for (i = 0; i < size; i++) |
| init_object (__builtin___bnd_narrow_ptr_bounds (objs + i, objs, |
| sizeof(object))); |
| } |
| </pre></div> |
| |
| </dd></dl> |
| |
| <dl> |
| <dt><a name="index-_005f_005fbuiltin_005f_005f_005fbnd_005fcopy_005fptr_005fbounds-1"></a>Built-in Function: <em>void *</em> <strong>__builtin___bnd_copy_ptr_bounds</strong> <em>(const void *<var>q</var>, const void *<var>r</var>)</em></dt> |
| <dd> |
| <p>This built-in function returns a new pointer with the value of <var>q</var>, |
| and associates it with the bounds already associated with pointer <var>r</var>. |
| With Pointer Bounds Checker off, the built-in function just returns the first |
| argument. |
| </p> |
| <div class="smallexample"> |
| <pre class="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_field, |
| objptr); |
| </pre></div> |
| |
| </dd></dl> |
| |
| <dl> |
| <dt><a name="index-_005f_005fbuiltin_005f_005f_005fbnd_005finit_005fptr_005fbounds-1"></a>Built-in Function: <em>void *</em> <strong>__builtin___bnd_init_ptr_bounds</strong> <em>(const void *<var>q</var>)</em></dt> |
| <dd> |
| <p>This built-in function returns a new pointer with the value of <var>q</var>, and |
| associates it with INIT (allowing full memory access) bounds. With Pointer |
| Bounds Checker off, the built-in function just returns the first argument. |
| </p> |
| </dd></dl> |
| |
| <dl> |
| <dt><a name="index-_005f_005fbuiltin_005f_005f_005fbnd_005fnull_005fptr_005fbounds-1"></a>Built-in Function: <em>void *</em> <strong>__builtin___bnd_null_ptr_bounds</strong> <em>(const void *<var>q</var>)</em></dt> |
| <dd> |
| <p>This built-in function returns a new pointer with the value of <var>q</var>, and |
| associates it with NULL (allowing no memory access) bounds. With Pointer |
| Bounds Checker off, the built-in function just returns the first argument. |
| </p> |
| </dd></dl> |
| |
| <dl> |
| <dt><a name="index-_005f_005fbuiltin_005f_005f_005fbnd_005fstore_005fptr_005fbounds-1"></a>Built-in Function: <em>void</em> <strong>__builtin___bnd_store_ptr_bounds</strong> <em>(const void **<var>ptr_addr</var>, const void *<var>ptr_val</var>)</em></dt> |
| <dd> |
| <p>This built-in function stores the bounds associated with pointer <var>ptr_val</var> |
| and location <var>ptr_addr</var> into Bounds Table. This can be useful to propagate |
| bounds from legacy code without touching the associated pointer’s memory when |
| pointers are copied as integers. With Pointer Bounds Checker off, the built-in |
| function call is ignored. |
| </p> |
| </dd></dl> |
| |
| <dl> |
| <dt><a name="index-_005f_005fbuiltin_005f_005f_005fbnd_005fchk_005fptr_005flbounds-1"></a>Built-in Function: <em>void</em> <strong>__builtin___bnd_chk_ptr_lbounds</strong> <em>(const void *<var>q</var>)</em></dt> |
| <dd> |
| <p>This built-in function checks if the pointer <var>q</var> is within the lower |
| bound of its associated bounds. With Pointer Bounds Checker off, the built-in |
| function call is ignored. |
| </p> |
| <div class="smallexample"> |
| <pre class="smallexample">extern void *__wrap_memset (void *dst, int c, size_t len) |
| { |
| if (len > 0) |
| { |
| __builtin___bnd_chk_ptr_lbounds (dst); |
| __builtin___bnd_chk_ptr_ubounds ((char *)dst + len - 1); |
| __real_memset (dst, c, len); |
| } |
| return dst; |
| } |
| </pre></div> |
| |
| </dd></dl> |
| |
| <dl> |
| <dt><a name="index-_005f_005fbuiltin_005f_005f_005fbnd_005fchk_005fptr_005fubounds-1"></a>Built-in Function: <em>void</em> <strong>__builtin___bnd_chk_ptr_ubounds</strong> <em>(const void *<var>q</var>)</em></dt> |
| <dd> |
| <p>This built-in function checks if the pointer <var>q</var> is within the upper |
| bound of its associated bounds. With Pointer Bounds Checker off, the built-in |
| function call is ignored. |
| </p> |
| </dd></dl> |
| |
| <dl> |
| <dt><a name="index-_005f_005fbuiltin_005f_005f_005fbnd_005fchk_005fptr_005fbounds-1"></a>Built-in Function: <em>void</em> <strong>__builtin___bnd_chk_ptr_bounds</strong> <em>(const void *<var>q</var>, size_t <var>size</var>)</em></dt> |
| <dd> |
| <p>This built-in function checks if [<var>q</var>, <var>q</var> + <var>size</var> - 1] is within |
| the lower and upper bounds associated with <var>q</var>. With Pointer Bounds Checker |
| off, the built-in function call is ignored. |
| </p> |
| <div class="smallexample"> |
| <pre class="smallexample">extern void *__wrap_memcpy (void *dst, const void *src, size_t n) |
| { |
| if (n > 0) |
| { |
| __bnd_chk_ptr_bounds (dst, n); |
| __bnd_chk_ptr_bounds (src, n); |
| __real_memcpy (dst, src, n); |
| } |
| return dst; |
| } |
| </pre></div> |
| |
| </dd></dl> |
| |
| <dl> |
| <dt><a name="index-_005f_005fbuiltin_005f_005f_005fbnd_005fget_005fptr_005flbound-1"></a>Built-in Function: <em>const void *</em> <strong>__builtin___bnd_get_ptr_lbound</strong> <em>(const void *<var>q</var>)</em></dt> |
| <dd> |
| <p>This built-in function returns the lower bound associated |
| with the pointer <var>q</var>, as a pointer value. |
| This is useful for debugging using <code>printf</code>. |
| With Pointer Bounds Checker off, the built-in function returns 0. |
| </p> |
| <div class="smallexample"> |
| <pre class="smallexample">void *lb = __builtin___bnd_get_ptr_lbound (q); |
| void *ub = __builtin___bnd_get_ptr_ubound (q); |
| printf ("q = %p lb(q) = %p ub(q) = %p", q, lb, ub); |
| </pre></div> |
| |
| </dd></dl> |
| |
| <dl> |
| <dt><a name="index-_005f_005fbuiltin_005f_005f_005fbnd_005fget_005fptr_005fubound-1"></a>Built-in Function: <em>const void *</em> <strong>__builtin___bnd_get_ptr_ubound</strong> <em>(const void *<var>q</var>)</em></dt> |
| <dd> |
| <p>This built-in function returns the upper bound (which is a pointer) associated |
| with the pointer <var>q</var>. With Pointer Bounds Checker off, |
| the built-in function returns -1. |
| </p> |
| </dd></dl> |
| |
| <hr> |
| <div class="header"> |
| <p> |
| Next: <a href="Cilk-Plus-Builtins.html#Cilk-Plus-Builtins" accesskey="n" rel="next">Cilk Plus Builtins</a>, Previous: <a href="Object-Size-Checking.html#Object-Size-Checking" accesskey="p" rel="prev">Object Size Checking</a>, Up: <a href="C-Extensions.html#C-Extensions" accesskey="u" rel="up">C Extensions</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Option-Index.html#Option-Index" title="Index" rel="index">Index</a>]</p> |
| </div> |
| |
| |
| |
| </body> |
| </html> |
