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).

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 library functions shown below 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
);

The Annex K Bounds-checking interfaces functions shown below also 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:

 
/* Annex K Functions */
 
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);

  /* ... */
}

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(), but copying takes place as if 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.

...

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 Parameters to a const-qualified Type 

functions define parameters that use the restrict qualification. The following is a list of the most common:

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,
  /* ... */
);

If any of the prece

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

Related Guidelines

Bibliography

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

...