Debian Codegraph @

upstream/debian-trixie/man3/memcpy.3

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