HOWTO · Arduino
Arduino memcpy and memmove
Learn how memcpy() and memmove() copy bytes in Arduino, when their memory regions may overlap, and how to size a destination safely.
On this page
Arduino programs can use the standard C library functions memcpy() and memmove() to copy bytes between memory locations. Choose memcpy() when the source and destination do not overlap; choose memmove() when they might. Both functions copy a caller-specified number of bytes, and neither knows the size of the destination buffer, so the program must ensure that the destination has enough room.
Using memcpy() to copy bytes
The function signature is void *memcpy(void *dest, const void *src, size_t n);. The dest argument points to the first byte to write, src points to the first byte to read, and n is a count of bytes. It is not a count of array elements. For an array, sizeof(array) gives its total size in bytes while the array is in scope; for a pointer, sizeof(pointer) gives the pointer’s size instead.
The source and destination ranges must not overlap. If even one byte belongs to both ranges, calling memcpy() has undefined behavior: the C and C++ language rules promise no particular result. It is not accurate to predict that the call will always overflow or corrupt data in a specific way. Use a separate destination buffer for an ordinary copy, and make sure it holds at least n writable bytes. The function does not allocate memory or check capacity.
Using memmove() with overlapping regions
void *memmove(void *dest, const void *src, size_t n); takes the same arguments and copies the same number of bytes. Unlike memcpy(), it is defined when the source and destination ranges overlap. The result is as if the original source bytes were first preserved and then written to the destination, so shifting part of an array within that same array is a suitable use.
This guarantee only addresses overlap. memmove() still writes n bytes starting at dest; it cannot determine the size of the object behind a pointer or prevent an out-of-bounds write. Check the available destination space before calling it, and ensure the source range itself is valid for n bytes.
Choose between memcpy() and memmove()
Use memcpy() when the two ranges are known to be separate. This expresses the simpler case directly and may allow an implementation to use an optimized non-overlapping copy. Use memmove() whenever overlap is possible or the relationship between the ranges is uncertain. Do not rely on a particular platform making overlapping memcpy() appear to work; compiler optimizations can make undefined behavior especially unpredictable.
For either function, first determine the byte count and the capacity of the destination. If copying a whole array, use its sizeof value while it is still an array, and size the destination for at least that many bytes. If copying elements of a type other than char, unsigned char, or std::byte, multiply the element count by sizeof(element) and ensure the operation is appropriate for that type; these functions copy object representations, not perform element-wise conversion or assignment.
Arduino example: copy an array
The following standalone C++ program demonstrates a separate-buffer array copy and a shift inside one buffer. It uses the same standard library calls available to Arduino C++ code. On a board, place the copy in setup() and send the destination to the Serial Monitor with Serial.println(); size the destination for the bytes you copy, including a string’s terminating null byte when you intend to print it as a C string.
Run this complete C++ example with a standard C++ compiler:
#include <cstdio>
#include <cstring>
int main() {
const char source[] = "LED";
char destination[sizeof(source)] = {};
std::memcpy(destination, source, sizeof(source));
std::printf("%s\n", destination);
char buffer[] = "ABCDE";
std::memmove(buffer + 1, buffer, 4);
std::printf("%s\n", buffer);
return 0;
}
LED
AABCD
Here, destination is exactly large enough for the source array, including its null terminator. The second copy moves four bytes one position to the right within buffer; its destination range overlaps its source range, so memmove() is the appropriate function. In an Arduino sketch, include Arduino.h as usual and replace the desktop std::printf() calls with Serial.println() after Serial.begin(...). The memory-copy calls and their sizing requirements remain the same.