summaryrefslogtreecommitdiffstats
path: root/man3/memcpy.3
blob: 553a2618b0839f0abaa78a45821792600ccef9a6 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
'\" t
.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk)
.\" and Copyright 2015 Michael Kerrisk <mtk.manpages@gmail.com>
.\"
.\" SPDX-License-Identifier: Linux-man-pages-copyleft
.\"
.\" References consulted:
.\"     Linux libc source code
.\"     Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991)
.\"     386BSD man pages
.\" Modified Sun Jul 25 10:41:09 1993 by Rik Faith (faith@cs.unc.edu)
.TH memcpy 3 2023-10-31 "Linux man-pages 6.7"
.SH NAME
memcpy \- copy memory area
.SH LIBRARY
Standard C library
.RI ( libc ", " \-lc )
.SH SYNOPSIS
.nf
.B #include <string.h>
.P
.BI "void *memcpy(void " dest "[restrict ." n "], const void " src "[restrict ." n ],
.BI "             size_t " n );
.fi
.SH DESCRIPTION
The
.BR memcpy ()
function copies \fIn\fP bytes from memory area
\fIsrc\fP to memory area \fIdest\fP.
The memory areas must not overlap.
Use
.BR memmove (3)
if the memory areas do overlap.
.SH RETURN VALUE
The
.BR memcpy ()
function returns a pointer to \fIdest\fP.
.SH ATTRIBUTES
For an explanation of the terms used in this section, see
.BR attributes (7).
.TS
allbox;
lbx lb lb
l l l.
Interface	Attribute	Value
T{
.na
.nh
.BR memcpy ()
T}	Thread safety	MT-Safe
.TE
.SH STANDARDS
C11, POSIX.1-2008.
.SH HISTORY
POSIX.1-2001, C89, SVr4, 4.3BSD.
.SH CAVEATS
Failure to observe the requirement that the memory areas
do not overlap has been the source of significant bugs.
(POSIX and the C standards are explicit that employing
.BR memcpy ()
with overlapping areas produces undefined behavior.)
Most notably, in glibc 2.13
.\" glibc commit 6fb8cbcb58a29fff73eb2101b34caa19a7f88eba
a performance optimization of
.BR memcpy ()
on some platforms (including x86-64) included changing the order
.\" From forward copying to backward copying
in which bytes were copied from
.I src
to
.IR dest .
.P
This change revealed breakages in a number of applications that performed
copying with overlapping areas.
.\" Adobe Flash player was the highest profile example:
.\"   https://bugzilla.redhat.com/show_bug.cgi?id=638477
.\"   Reported: 2010-09-29 02:35 EDT by JCHuynh
.\"   Bug 638477 - Strange sound on mp3 flash website
.\"
.\"   https://sourceware.org/bugzilla/show_bug.cgi?id=12518
.\"   Bug 12518 - memcpy acts randomly (and differently) with overlapping areas
.\"   Reported:       2011-02-25 02:26 UTC by Linus Torvalds
.\"
Under the previous implementation,
the order in which the bytes were copied had fortuitously hidden the bug,
which was revealed when the copying order was reversed.
In glibc 2.14,
.\" glibc commit 0354e355014b7bfda32622e0255399d859862fcd
a versioned symbol was added so that old binaries
(i.e., those linked against glibc versions earlier than 2.14)
employed a
.BR memcpy ()
implementation that safely handles the overlapping buffers case
(by providing an "older"
.BR memcpy ()
implementation that was aliased to
.BR memmove (3)).
.SH SEE ALSO
.BR bcopy (3),
.BR bstring (3),
.BR memccpy (3),
.BR memmove (3),
.BR mempcpy (3),
.BR strcpy (3),
.BR strncpy (3),
.BR wmemcpy (3)