memcpy, memcpy_s
Defined in header <string.h>
|
||
---|---|---|
(1) | ||
|
(until C99) | |
|
(since C99) | |
|
(2) | (since C11) |
1) Copies count
characters from the object pointed to by src
to the object pointed to by dest
. Both objects are interpreted as arrays of unsigned char
.
The behavior is undefined if access occurs beyond the end of the dest array. If the objects overlap (which is a violation of the restrict contract) (since C99), the behavior is undefined. The behavior is undefined if either dest
or src
is a null pointer.
2) Same as (1), except that the following errors are detected at runtime and cause the entire destination range [dest, dest+destsz)
to be zeroed out (if both dest
and destsz
are valid), as well as call the currently installed constraint handler function:
dest
orsrc
is a null pointerdestsz
orcount
is greater thanRSIZE_MAX
count
is greater thandestsz
(buffer overflow would occur)- the source and the destination objects overlap
The behavior is undefined if the size of the character array pointed to by dest
< count
<= destsz
; in other words, an erroneous value of destsz
does not expose the impending buffer overflow. As with all bounds-checked functions, memcpy_s
is only guaranteed to be available if __STDC_LIB_EXT1__
is defined by the implementation and if the user defines __STDC_WANT_LIB_EXT1__
to the integer constant 1 before including string.h
.
Parameters
dest | - | pointer to the object to copy to |
destsz | - | max number of bytes to modify in the destination (typically the size of the destination object) |
src | - | pointer to the object to copy from |
count | - | number of bytes to copy |
Return value
1) Returns a copy of dest
2) Returns zero on success and non-zero value on error. Also on error, if dest
is not a null pointer and destsz
is valid, writes destsz
zero bytes in to the destination array.
Notes
memcpy
may be used to set the effective type of an object obtained by an allocation function.
memcpy
is the fastest library routine for memory-to-memory copy. It is usually more efficient than strcpy
, which must scan the data it copies or memmove
, which must take precautions to handle overlapping inputs.
Several C compilers transform suitable memory-copying loops to memcpy
calls.
Where strict aliasing prohibits examining the same memory as values of two different types, memcpy
may be used to convert the values.
Example
#define __STDC_WANT_LIB_EXT1__ 1
#include <stdio.h>
#include <stdint.h>
#include <inttypes.h>
#include <string.h>
#include <stdlib.h>
int main(void)
{
// simple usage
char source[] = "once upon a midnight dreary...", dest[4];
memcpy(dest, source, sizeof dest);
for(size_t n = 0; n < sizeof dest; ++n)
putchar(dest[n]);
// setting effective type of allocated memory to be int
int *p = malloc(3*sizeof(int)); // allocated memory has no effective type
int arr[3] = {1,2,3};
memcpy(p,arr,3*sizeof(int)); // allocated memory now has an effective type
// reinterpreting data
double d = 0.1;
// int64_t n = *(int64_t*)(&d); // strict aliasing violation
int64_t n;
memcpy(&n, &d, sizeof d); // OK
printf("\n%a is %" PRIx64 " as an int64_t\n", d, n);
#ifdef __STDC_LIB_EXT1__
set_constraint_handler_s(ignore_handler_s);
char src[] = "aaaaaaaaaa";
char dst[] = "xyxyxyxyxy";
int r = memcpy_s(dst,sizeof dst,src,5);
printf("dst = \"%s\", r = %d\n", dst,r);
r = memcpy_s(dst,5,src,10); // count is greater than destsz
printf("dst = \"");
for(size_t ndx=0; ndx<sizeof dst; ++ndx) {
char c = dst[ndx];
c ? printf("%c", c) : printf("\\0");
}
printf("\", r = %d\n", r);
#endif
}
Possible output:
once
0x1.999999999999ap-4 is 3fb999999999999a as an int64_t
dst = "aaaaayxyxy", r = 0
dst = "\0\0\0\0\0yxyxy", r = 22
References
C11 standard (ISO/IEC 9899:2011):
- 7.24.2.1 The memcpy function (p: 362)
- K.3.7.1.1 The memcpy_s function (p: 614)
C99 standard (ISO/IEC 9899:1999):
- 7.21.2.1 The memcpy function (p: 325)
C89/C90 standard (ISO/IEC 9899:1990):
- 4.11.2.1 The memcpy function
See also
(C11) |
moves one buffer to another (function) |
(C95)(C11) |
copies a certain amount of wide characters between two non-overlapping arrays (function) |
© cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
http://en.cppreference.com/w/c/string/byte/memcpy