Lines Matching full:pointer
21 ``__counted_by(N)`` annotation to parameter ``ptr``, indicating that the pointer
29 pointer dereference, ensuring that the program does not access memory outside
73 In our model, every pointer has an explicit or implicit bounds attribute that
93 A bounds annotation defines an invariant for the pointer type, and the model
94 ensures that this invariant remains true. In the example below, pointer ``p``
98 out-of-bounds access to the pointer. To avoid this, the compiler employs
117 incorporates the concept of a "wide pointer" (a.k.a. fat pointer) – a larger
118 pointer that carries bounds information alongside the pointer value. Utilizing
126 ``-fbounds-safety`` harmonizes the wide pointer and the bounds annotation
128 model, local variables of pointer type are implicitly treated as wide pointers,
153 The C language allows pointer arithmetic on arbitrary pointers and this has been
155 pointing to a single object and incrementing or decrementing such a pointer
156 immediately makes the pointer go out-of-bounds. To prevent this unsafety,
157 ``-fbounds-safety`` provides the annotation ``__single`` that causes pointer
160 * ``__single`` : indicates that the pointer is either pointing to a single
161 object or null. Hence, pointers with ``__single`` do not permit pointer
163 ``__single`` pointer is allowed but it requires a null check. Upper and lower
164 bounds checks are not required because the ``__single`` pointer should point
171 a ``__single`` pointer is utilized for pointer arithmetic or array access, as
172 these operations would immediately cause the pointer to exceed its bounds.
174 to pointers. In the following example, the pointer on parameter p is
176 generates an error suggesting to add ``__counted_by`` to the pointer.
191 pointer variable and another variable (or expression) containing the bounds
192 information of the pointer. In the following example, ``__counted_by(count)``
195 of a pointer is often available adjacent to the pointer itself, e.g., at another
208 ``__ended_by``. These annotations do not change the pointer representation,
211 * ``__counted_by(N)`` : The pointer points to memory that contains ``N``
218 * ``__sized_by(N)`` : The pointer points to memory that contains ``N`` bytes.
223 * ``__ended_by(P)`` : The pointer has the upper bound of value ``P``, which is
224 one past the last element of the pointer. In other words, this annotation
225 describes a range that starts with the pointer that has this annotation and
228 to the pointer ``Q``. This is used for "iterator" support in C where you're
229 iterating from one pointer value to another until a final pointer value is
230 reached (and the final pointer value is not dereferencable).
232 Accessing a pointer outside the specified bounds causes a run-time trap or a
234 when the pointer and/or the related value containing the bounds information are
239 violate the ``__counted_by`` annotation because a null pointer does not point to
247 // This is not allowed as it creates a null pointer with non-zero length
251 However, there are use cases where a pointer is either a null pointer or is
255 ``__ended_by_or_null(P)``. Accessing a pointer with any of these bounds
256 annotations will require an extra null check to avoid a null pointer
262 A wide pointer (sometimes known as a "fat" pointer) is a pointer that carries
265 pointers, hence the name "wide pointer". The memory layout of a wide pointer is
266 equivalent to a struct with the pointer, upper bound, and (optionally) lower
272 void* pointer; // Address used for dereferences and pointer arithmetic
280 normal pointers to allow standard pointer operations, such as pointer
282 pointer arithmetic, with some restrictions on bounds-unsafe uses.
286 pointer has either of these annotations, the compiler changes the pointer to the
287 corresponding wide pointer. This means these annotations will break the ABI and
291 * ``__bidi_indexable`` : A pointer with this annotation becomes a wide pointer
296 and the pointers can be incremented or decremented using pointer arithmetic. A
297 ``__bidi_indexable`` pointer is allowed to hold an out-of-bounds pointer
298 value. While creating an OOB pointer is undefined behavior in C,
299 ``-fbounds-safety`` makes it well-defined behavior. That is, pointer
303 OOB pointer is prevented via a run-time bounds check.
305 * ``__indexable`` : A pointer with this annotation becomes a wide pointer
308 pointers do not have a separate lower bound, the pointer value itself acts as
309 the lower bound. An ``__indexable`` pointer can only be incremented or indexed
312 check to ensure pointer arithmetic doesn't make the pointer smaller than the
313 original ``__indexable`` pointer (Note that ``__indexable`` doesn't have a
314 lower bound so the pointer value is effectively the lower bound). As pointer
315 arithmetic overflow will make the pointer smaller than the original pointer,
317 ``__indexable`` pointer is allowed to have a pointer value above the upper
318 bound and creating such a pointer is well-defined behavior. Dereferencing such
319 a pointer, however, will cause a run-time trap.
321 * ``__bidi_indexable`` offers the best flexibility out of all the pointer
323 any pointer operation. However, this comes with the largest code size and
324 memory cost out of the available pointer annotations in this model. In some
330 such as local pointer variables — that is, if the programmer does not specify
331 another bounds annotation, a local pointer variable is implicitly
333 bounds information and have no restrictions on kinds of pointer operations that
359 ``__terminated_by`` pointer beyond its end. Calculating the location of the end
368 ``__terminated_by`` pointer ``P`` to an ``__indexable`` pointer.
370 * ``__null_terminated`` : The pointer or array is terminated by ``NULL`` or
371 ``0``. Modifying the terminator or incrementing the pointer beyond it is
374 * ``__terminated_by(T)`` : The pointer or array is terminated by ``T`` which is
375 a constant expression. Accessing or incrementing the pointer beyond the
382 A pointer with the ``__unsafe_indexable`` annotation behaves the same as a plain
383 C pointer. That is, the pointer does not have any bounds information and pointer
390 Default pointer types
399 annotations to pointer types.
400 Default annotations apply to pointer types of declarations
402 ``-fbounds-safety`` applies default bounds annotations to pointer types used in
404 the pointer. A pointer type is ABI-visible if changing its size or
409 considers the outermost pointer types of local variables as non-ABI visible. The
410 rest of the pointers such as nested pointer types, pointer types of global
420 be ``__unsafe_indexable``. Non-ABI visible pointers — the outermost pointer
433 In system headers, the default pointer attribute for ABI-visible pointers is set
459 ABI, taking the address of such a modified type could create a pointer type that
462 pointer to ``int *__bidi_indexable``. On the other hand, in ``void foo(int
463 **)``, the parameter type is a pointer to ``int *__single`` (i.e., ``void
464 foo(int *__single *__single)``) (or a pointer to ``int *__unsafe_indexable`` if
466 pointers whose elements have incompatible pointer attributes. This way,
477 // incompatible nested pointer type 'int *__single*__single'
500 In order to avoid an implicitly wide pointer from silently breaking the ABI, the
501 compiler reports a warning when ``typeof()`` is used on an implicit wide pointer
504 .. _Default pointer types in typeof:
506 Default pointer types in ``typeof()``
552 bounds annotation on the named pointer types. For example, ``typeof(int*)``
570 Default pointer types in ``sizeof()``
574 bounds annotation on the named pointer types. This means if a bounds annotation
575 is not specified, the evaluated pointer type is treated identically to a plain C
576 pointer type. Therefore, ``sizeof(int*)`` remains the same with or without
586 error as described in :ref:`Default pointer types in typeof`.
596 Default pointer types in ``alignof()``
601 an implicit bounds annotation on the pointer types named inside ``alignof()``.
603 ``-fbounds-safety``, evaluating into the alignment of the raw pointer ``T *``.
608 the original pointer. Therefore, ``alignof(int *__bidi_indexable)`` is equal to
612 Default pointer types used in C-style casts
615 A pointer type used in a C-style cast (e.g., ``(int *)src``) inherits the same
616 pointer attribute in the type of src. For instance, if the type of src is ``T
622 Pointer casts can have explicit bounds annotations. For instance, ``(int
634 Default pointer types in typedef
637 Pointer types in ``typedef``\s do not have implicit default bounds annotations.
639 following example shows that no pointer annotation is specified in the ``typedef
640 pint_t`` while each instance of ``typedef``'ed pointer gets its bounds
653 Pointer types in a ``typedef`` can still have explicit annotations, e.g.,
657 Array to pointer promotion to secure arrays (including VLAs)
663 In C, arrays on function prototypes are promoted (or "decayed") to a pointer to
696 // and cannot be used for pointer arithmetic
702 automatically promoted (or "decayed") to a pointer to its first element (e.g.,
739 additional checks when a pointer object and/or its related value containing the
742 For example, ``__single`` expresses an invariant that the pointer must either
743 point to a single valid object or be a null pointer. To maintain this invariant,
744 the compiler inserts checks when initializing a ``__single`` pointer, as shown
798 bound of the pointer is derived. If the source pointer has ``__sized_by``,
801 ``ptr`` is ``void *__sized_by(size)``), because when the ``__sized_by`` pointer
810 ``ptr + size`` may still overflow if the ``__sized_by`` pointer is created from
815 is the return type of ``malloc()``. Hence, the pointer arithmetic doesn't
825 way to violate the bounds invariant of the destination's pointer annotation.
830 Two pointers that have different bounds annotations on their nested pointer
835 only apply to the top pointer types. ``__unsafe_indexable`` cannot be converted
836 to any other safe pointer types (``__single``, ``__bidi_indexable``,
838 this conversion, ``__unsafe_forge_bidi_indexable(type, pointer, char_count)`` to
839 convert pointer to a ``__bidi_indexable`` pointer of type with ``char_count``
840 bytes available and ``__unsafe_forge_single(type, pointer)`` to convert pointer
841 to a single pointer of type type. The following examples show the usage of these
877 * Similar to ``__unsafe_indexable``, any non-pointer type (including ``int``,
878 ``intptr_t``, ``uintptr_t``, etc.) cannot be converted to any safe pointer
882 * Any safe pointer types can cast to ``__unsafe_indexable`` because it doesn't
891 determine the upper bound of a single void pointer.
904 compiler may insert run-time checks to ensure the pointer has at least a
905 single element or is a null pointer.
907 * ``__bidi_indexable`` casts to ``__indexable`` if the pointer does not have an
908 underflow. The compiler may insert run-time checks to ensure the pointer is
912 ``__bidi_indexable`` gets the lower bound same as the pointer value.
922 * ``__terminated_by(T)`` cannot cast to any safe pointer type without the same
933 safe pointer PTR to a ``__terminated_by(T)`` pointer. ``PTR_TO_TERM`` is an
936 array in order to locate the end of the pointer (or the upper bound).
940 pointer given any pointer ``P``. Tmust be a pointer type.