memcpy, memcpy_s
From cppreference.com
Defined in header
<string.h>
|
||
(1) | ||
void* memcpy( void *dest, const void *src, size_t count );
|
(until C99) | |
void* memcpy( void *restrict dest, const void *restrict src, size_t count );
|
(since C99) | |
errno_t memcpy_s( void *restrict dest, rsize_t destsz,
const void *restrict src, rsize_t count ); |
(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. If the objects overlap (which is a violation of the restrict contract) (since C99), the behavior is undefined.
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 pointer -
destsz
orcount
is greater than RSIZE_MAX -
count
is greater thandestsz
(buffer overflow would occur) - the source and the destination objects overlap
-
- As 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 includingstring.h
.
Contents |
[edit] Parameters
dest | - | pointer to the memory location to copy to |
destsz | - | max number of bytes to modify in the destination (typically the size of the destination object) |
src | - | pointer to the memory location to copy from |
count | - | number of bytes to copy |
[edit] 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.[edit] 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.
[edit] Example
Run this code
#include <stdio.h> #include <stdint.h> #include <inttypes.h> #include <string.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]); // 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); }
Output:
once 0x1.999999999999ap-4 is 3fb999999999999a as an int64_t
[edit] 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
[edit] See also
(C11)
|
moves one buffer to another (function) |
(C95)(C11)
|
copies a certain amount of wide characters between two non-overlapping arrays (function) |
C++ documentation for memcpy
|