man3/memcpy.3

   1 .\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk)
   2 .\" and Copyright 2015 Michael Kerrisk <mtk.manpages@gmail.com>
   3 .\"
   4 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
   5 .\"
   6 .\" References consulted:
   7 .\"     Linux libc source code
   8 .\"     Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991)
   9 .\"     386BSD man pages
  10 .\" Modified Sun Jul 25 10:41:09 1993 by Rik Faith (faith@cs.unc.edu)
  11 .TH MEMCPY 3 2021-03-22 "Linux man-pages (unreleased)" "Linux Programmer's Manual"
  12 .SH NAME
  13 memcpy \- copy memory area
  14 .SH LIBRARY
  15 Standard C library
  16 .RI ( libc ", " \-lc )
  17 .SH SYNOPSIS
  18 .nf
  19 .B #include <string.h>
  20 .PP
  21 .BI "void *memcpy(void *restrict " dest ", const void *restrict " src \
  22 ", size_t " n );
  23 .fi
  24 .SH DESCRIPTION
  25 The
  26 .BR memcpy ()
  27 function copies \fIn\fP bytes from memory area
  28 \fIsrc\fP to memory area \fIdest\fP.
  29 The memory areas must not overlap.
  30 Use
  31 .BR memmove (3)
  32 if the memory areas do overlap.
  33 .SH RETURN VALUE
  34 The
  35 .BR memcpy ()
  36 function returns a pointer to \fIdest\fP.
  37 .SH ATTRIBUTES
  38 For an explanation of the terms used in this section, see
  39 .BR attributes (7).
  40 .ad l
  41 .nh
  42 .TS
  43 allbox;
  44 lbx lb lb
  45 l l l.
  46 Interface       Attribute       Value
  47 T{
  48 .BR memcpy ()
  49 T}      Thread safety   MT-Safe
  50 .TE
  51 .hy
  52 .ad
  53 .sp 1
  54 .SH STANDARDS
  55 POSIX.1-2001, POSIX.1-2008, C89, C99, SVr4, 4.3BSD.
  56 .SH NOTES
  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 .PP
  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)