An object that is accessed through a restrict-qualified pointer has a special association with that pointer. This association requires that all accesses to that object use, directly or indirectly, the value of that particular pointer. The intended use of the restrict qualifier is to promote optimization, and deleting all instances of the qualifier from a program does not change its meaning (that is, observable behavior). In the absence of this qualifier, other pointers can alias this object. Cacheing Caching the value in an object designated through a  restricta restrict-qualified pointer is safe at the beginning of the block in which the pointer is declared , because no pre-existing preexisting aliases may also be used to reference that object. The cached value must be restored to the object by the end of the block, where pre-existing preexisting aliases again become available. New aliases may be formed within the block, but these must all depend on the value of the restrict-qualified pointer , so that they can be identified and adjusted to refer to the cached value. For a  restricta restrict-qualified pointer at file scope, the block is the body of each function in the file [Douglas Walls 2006]. Developers should be aware that the C++ does not support the the restrict qualifier, however, but some C++ compiler vendor support a implementations support an equivalent qualifier as an extension. 

Overlapping Objects

The restrict qualifier requires that the pointers do not reference overlapping objects. If the objects referenced by arguments to functions overlap (meaning the objects share some common memory addresses), the behavior is undefined.

Noncompliant Code Example

In this noncompliant code example, the file scope declarations assert that if an object is accessed using one of a, b, or c, and that object is modified anywhere in the program, then it is never accessed using either of the other two.

int * restrict a;
int * restrict b;

extern int c[];
 
int main(void) {
  c[0] = 17; 
  c[1] = 18;
  a = &c[0]; 
  b = &c[1];
  *a = *b; /* undefined behavior */
}

The C Standard [ISO/IEC 9899:2024] identifies the following undefined behavior:

A restrict-qualified pointer is assigned a value based on another restricted pointer whose associated block neither began execution before the block associated with this pointer, nor ended before the assignment (6.7.4.2).

This is an oversimplification, however, and it is important to review the formal definition of restrict in subclause 6.7.3.1 of the C Standard to properly understand undefined behaviors associated with the use of restrict-qualified pointers.

Overlapping Objects

The restrict qualifier requires that the pointers do not reference overlapping objects. If the objects referenced by arguments to functions overlap (meaning the objects share some common memory addresses), the behavior is undefined.

Noncompliant Code Example

This code example is noncompliant because an assignment is made between two restrict-qualified pointers in the same scope: 

int *restrict a;
int *restrict b;

extern int c[];
 
int main(void) {
  c[0] = 17; 
  c[1] = 18;
  a = &c[0]; 
  b = &c[1];
  a = b; /* Undefined behavior */
  /* ... */
}

Note that undefined behavior occurs only when a is assigned to b. It is valid for a and b to point into the same array object, provided the range of elements accessed through one of the pointers does not overlap with the range of elements accessed through the other pointer.

Compliant

...

Solution

One way to eliminate the undefined behavior is simply to remove the restrict-qualification from the affected pointers. :

int * a;
int * b;

extern int c[];
 
int main(void) {
  c[0] = 17; 
  c[1] = 18;
  a = &c[0]; 
  b = &c[1];
  *a = *b; /* valid defined behaviorDefined behavior */
  /* ... */
}

...

restrict-

...

Qualified Function Parameters

 When When calling functions that have restrict-qualified function parameters important that pointers , it is important that the pointer arguments do not reference overlapping objects If one if one or more of the objects the pointers are used to modify memory. Thus Consequently, it is important to understand the semantics of the function being called.

Noncompliant Code Example

In this noncompliant code example, the function f() accepts three parameters.   The function copies copies n integers from the int arrray array referenced by the restrict-qualified pointer p to the int array referenced by the restrict-qualified pointer q.    Because Because the object destination array is modified during each execution of the function (for which n is nonzero), if an object the array is accessed through one of the pointer parameters, it cannot also be accessed through the other.  Declaring  Declaring these function parameters as restrict-qualified pointers allows aggressive optimization by the compiler but can also result in undefined behavior if these pointers refer to overlapping objects.

void #include <stddef.h>
void f(size_t n, int * restrict p, const int * restrict q) {
  while (n-- > 0) {
    *p++ = *q++;
  }
}
 
void g(void) {
  extern int d[100];

  /* ... */
  f(50, d + 1, d); /* undefinedUndefined behavior */
}

The function g() declares an array d consisting of 100 int values and then invokes f() to copy memory from one area of the array to another. This call has undefined behavior because each of d[1] through d[49]  is accessed through both p and q .

Compliant Solution

In this compliant solution, the function f() is unchanged but the programmer has ensured that none of the calls to f() result in undefined behavior.  The  The call of to f() in g() is valid because the storage is allocated to d is effectively divided into two disjoint objects.

#include <stddef.h>
void f(intsize_t n, int * restrict p, const int * restrict q) {
   while (n-- > 0) {
     *p++ = *q++;
  } 
}
 
void g(void) {
  extern int d[100];

  /* ... */
  f(50, d + 50, d); /* valid definedDefined behavior  */
}

Noncompliant Code Example

In this noncompliant code example, the function hfunction add() adds the integer array referenced by the the restrict-qualified pointers q pointers lhs to the integer array referenced by the the restrict-qualified pointer r and pointer rhs and stores the result in the restrict-qualified pointer referenced by p.  The the call h res. The function f() declares an array a consisting of 100 int values and then invokes add() to copy memory from one area of the array to another. The call add(100, a, a, a) has undefined behavior because the object modifed by p modified by res is accessed by q by lhs and r rhs.

#include <stddef.h>
 
void hadd(size_t n, int * restrict pres, const int * restrict q,lhs,
       const int * restrict rrhs) {
  for (size_t i = 0; i < n; i++i) {
    pres[i] = qlhs[i] + rrhs[i];
  }
}
 
void jf(void) {

  int a[100]; 
  hadd(100, a, a, a); /* undefinedUndefined behavior */
}

The function g() declares an array d consisting of 100 int values and then invokes f() to copy memory from one area of the array to another. This call has undefined behavior because each of d[1]  through d[49]  is accessed through both p  and q .

Compliant Solution

Compliant Solution

In this In this compliant solution, an unmodified object is aliased through two restricted pointers. Because a  and Because a and b are disjoint arrays, a call of the form hadd(100, a, b, b)  has has defined behavior, because array array b is not modified within function h function add.

#include <stddef.h>
void hadd(size_t n, int * restrict pres, const int * restrict qlhs,
         const int * restrict rrhs) {
  for (size_t i = 0; i < n; i++i) {
    pres[i] = qlhs[i] + rrhs[i];
  }
}
 
void jf(void) {
   int a[100]; 
   int b[100];
   hadd(100, a, b, b); /* valid definedDefined behavior  */
}

...

Invoking Library Functions with restrict-

...

Qualified Pointers

Ensure that restrict-qualified source and destination pointers do not reference overlapping objects when invoking library functions. The standard For example, the following table lists C standard library functions shown below that copy memory from a source object referenced by a restrict-qualified pointer to a destination object that is also referenced by a restrict-qualified pointer: 

void *memcpy(
  void * restrict s1,
  const void * restrict s2,
  size_t n
);
 
char *strcpy(
  char * restrict s1,
  const char * restrict s2
);
 
char *strncpy(
  char * restrict s1,
  const char * restrict s2,
  size_t n
);

char *strcat(
  char * restrict s1,
  const char * restrict s2
);
 
char *strncat(
  char * restrict s1,
  const char * restrict s2, 
  size_t n
);

...

If the objects referenced by arguments to functions overlap (meaning the objects share some common memory addresses), the behavior is undefined. (See also undefined behavior 68.) The result of the functions is unknown, and data may be corrupted. As a result, these functions must never be passed pointers to overlapping objects. If data must be copied between objects that share common memory addresses, a copy function guaranteed to work on overlapping memory, such as memmove(), should be used.

Noncompliant Code Example

In this noncompliant code example, the values of objects referenced by ptr1 and ptr2 become unpredictable after the call to memcpy() because their memory areas overlap:

#include <string.h>
 
void func(void) {
  char c_str[]= "test string";
  char *ptr1 = c_str;
  char *ptr2;

  ptr2 = ptr1 + 3;
  /* Undefined behavior because of overlapping objects */
  memcpy(ptr2, ptr1, 6);  
  /* ... */
}

Compliant Solution

In this compliant solution, the call to memcpy() is replaced with a call to memmove(). The memmove() function performs the same operation as memcpy() when the memory regions do not overlap. When the memory regions do overlap, the n characters from the object pointed to by the source (ptr1) are first copied into a temporary array of n characters that does not overlap the objects pointed to by the destination (ptr2) or the source. The n characters from the temporary array are then copied into the object pointed to by the destination.

#include <string.h>

void func(void) {
  char c_str[]= "test string";
  char *ptr1 = c_str;
  char *ptr2;

  ptr2 = ptr1 + 3;
  memmove(ptr2, ptr1, 6);  /* Replace call to memcpy() */
  /* ... */
}

Similar solutions using memmove() can replace the string functions as long as care is taken regarding the byte size of the characters and proper null-termination of the copied string.

Calling Functions with restrict-Qualified Pointer to a const-Qualified Type 

Ensure that functions that accept a restrict-qualified pointer to a const-qualified type do not modify the object referenced by that pointer. Formatted input and output standard library functions frequently fit this description. The following table lists of some of the common functions for which the format argument is a restrict-qualified pointer to a const-qualified type.

For formatted output functions such as printf(), it is unlikely that a programmer would modify the format string. However, an attacker may attempt to do so if a program violates FIO30-C. Exclude user input from format strings and passes tainted values as part of the format string. 

Noncompliant Code Example

In this noncompliant code example, the programmer is attempting to overwrite the format string with a string value read in from stdin such as "%d%f 1 3.3" and use the resulting modified string of "%s%d%f" to input the subsequent values of 1 and 3.3:

#include <stdio.h>
 
void func(void) {
  int i;
  float x;
  char format[100] = "%s";
  /* Undefined behavior */
  int n = scanf(format, format + 2, &i, &x); 

errno_t memcpy_s(
  void * restrict s1, 
  rsize_t s1max,
  const void * restrict s2, 
  rsize_t n
);
 
errno_t strcpy_s(
  char * restrict s1,
  rsize_t s1max,
  const char * restrict s2 
);
 
errno_t strncpy_s(
  char * restrict s1,
  rsize_t s1max,
  const char * restrict s2,
  rsize_t n
);

errno_t strcat_s(
  char * restrict s1,
  rsize_t s1max,
  const char * restrict s2
);
 
errno_t strncat_s(
  char * restrict s1,
  rsize_t s1max,
  const char * restrict s2,
  rsize_t n
);
 
char *strtok_s(
  char * restrict s1,
  rsize_t * restrict s1max,
  const char * restrict s2,
  char ** restrict ptr
);

If the objects referenced by arguments to functions overlap (meaning the objects share some common memory addresses), the behavior is undefined. See also undefined behavior 68 in Appendix J of the C Standard. The result of the functions is unknown and data may be corrupted. As a result, these functions must never be passed pointers to overlapping objects. If data must be copied between objects that share common memory addresses, a copy function guaranteed to work on overlapping memory, such as memmove(), should be used.

Noncompliant Code Example

In this noncompliant code example, the values of objects referenced by ptr1 and ptr2 become unpredictable after the call to memcpy() because their memory areas overlap:

#include <string.h>
 
void func(void) {
  char c_str[]= "test string";
  char *ptr1 = c_str;
  char *ptr2;

  ptr2 = ptr1 + 3;
  memcpy(ptr2, ptr1, 6); /* undefined behavior due to overlapping objects*/
  
  /* ... */
}

Compliant Solution

In this compliant solution, the call to memcpy() is replaced with a call to memmove(). The memmove() function performs the same operation as memcpy() when the memory regions do not overlap. When the memory regions do overlap the n characters from the object pointed to by the source (ptr1) are first copied into a temporary array of n characters that does not overlap the objects pointed to by the destination (ptr2) or the source. The n characters from the temporary array are then copied into the object pointed to by the destination.

#include <string.h>

void func(void) {char c_str[]= "test string";
  char *ptr1 = c_str;
  char *ptr2;

  ptr2 = ptr1 + 3;
  memmove(ptr2, ptr1, 6);  /* Replace call to memcpy() */

  /* ... */
}

Similar solutions using memmove() can replace the string functions as long as care is taken regarding the byte size of the characters and proper null-termination of the copied string.

Calling Functions with restrict-qualified Pointer to a const-qualified Type 

Ensure that functions that accept a restrict-qualified pointer to a const-qualified type do not modify the object referenced by that pointer. Formatted input and output standard library functions frequently fit this descriptoin. The following is a list of the common functions where the format argument is a restrict-qualified pointer to a const-qualified type:

Compliant Solution

The intended results are achieved by this compliant solution:

#include <stdio.h>
 
void func(void) {
  int i;
  float x;
  int n = scanf("%d%f", &i, &x); /* Defined behavior  */ 

int printf(
  const char * restrict format,
  /* ... */
);

 
int scanf(
  const char * restrict format,
  /* ... */
);

 
int sprintf(
  char * restrict s,
  const char * restrict format,
  /* ... */
);

 
int snprintf(
  char * restrict s,
  size_t n,
  const char * restrict format,
  /* ... */
);

For formatted output functions such as printf(), it is unlikely that a programmer would modify the format string.  However, an attacker may attempt this if a program violates FIO30-C. Exclude user input from format strings and passes tainted values as part of the format string. 

Noncompliant Code Example

In this noncompliant code example, the programmer is attempting to overwrite the format string with a string value read in from stdin such as "%d%f 1 3.3"  , and use the resulting modified string of "%s%d%f" to input the subsequent values of 1 and 3.3:

#include <stdio.h>
/* ...  */
char format[100] = "%s";
int i; 
float x;
int n = scanf(format, format + 2, &i, &x); /* undefined behavior */

Compliant Solution

The same results can be achieved as shown in this compliant solution.

#include <stdio.h>
/* ... */
int i; 
float x;
int n = scanf("%d%f", &i, &x); /* valid defined behavior  */ 

Outer to-inner assignments between restricted pointers

The assignment between restricted pointers declared in nested blocks from a outer block to a inner block have defined behavior.

Noncompliant Code Example

The assignment of restrict-qualified pointers to other restrict-qualified pointers within the same block has undefined behavior.

 {
  int * restrict p1;
  int * restrict q1;

  int * restrict p2 = p1; /* undefined behavior */ 
  int * restrict q2 = q1; /* undefined behavior */ 
 }

Compliant Solution 

The same results can be achieved as shown in this compliant solution.

 {
  int * restrict p1;   
  int * restrict q1;
  {  /* added inner block begin */
    int * restrict p2 = p1;  /* valid defined behavior  */    
    int * restrict q2 = q1;  /* valid defined behavior  */ 
    ...
  } /* added inner block end */
}

Risk Assessment

Using functions such as memcpy(), strcpy(), strncpy(), sscanf(), sprintf(), snprintf(), mbstowcs(), and wcstombs() to copy overlapping objects results in undefined behavior that can be exploited to cause data integrity violations.

Related Vulnerabilities

Search for vulnerabilities resulting from the violation of this rule on the CERT website.

Automated Detection

...

Tool

...

Version

...

Checker

...

Description

...

LDRA tool suite

...

}

Outer-to-Inner Assignments between Restricted Pointers

The assignment between restrict-qualified pointers declared in an inner nested block from an outer block has defined behavior.

Noncompliant Code Example

The assignment of restrict-qualified pointers to other restrict-qualified pointers within the same block has undefined behavior:

void func(void) {
  int *restrict p1;
  int *restrict q1;

  int *restrict p2 = p1; /* Undefined behavior */ 
  int *restrict q2 = q1; /* Undefined behavior */ 
 }

Compliant Solution 

The intended results can be achieved using an inner nested block, as shown in this compliant solution:

void func(void) {
  int *restrict p1;   
  int *restrict q1;
  {  /* Added inner block */
    int *restrict p2 = p1; /* Valid, well-defined behavior */    
    int *restrict q2 = q1; /* Valid, well-defined behavior */ 
  }
}

Risk Assessment

The incorrect use of restrict-qualified pointers can result in undefined behavior that might be exploited to cause data integrity violations.

Related Vulnerabilities

Search for vulnerabilities resulting from the violation of this rule on the CERT website.

Automated Detection

Related Guidelines

Key here (explains table format and definitions)

1. MISRA Rule 8.14 prohibits the use of the restrict keyword except in C standard library functions. 

Bibliography

...

Image Added Image Added Image Added

...

480 S 489 S

...

Related Guidelines

Bibliography

Douglas Walls.  How to Use the Qualifier in C.  Sun ONE Tools Group, Sun Microsystems, July 2003 (revised March 2006)               

Image Removed Image Removed Image Removed