Go to main content

man pages section 3: Basic Library Functions

Exit Print View

Updated: Thursday, June 13, 2019
 
 

memcpy(3C)

Name

memory, memccpy, memchr, memcmp, memcpy, memmove, memset, memmem - memory operations

memcpy_s, memmove_s, memset_s - memory operations with additional safety checks

Synopsis

#include <string.h>

void *memccpy(void *restrict s1, const void *restrict s2,
     int c, size_t n);
void *memchr(const void *s, int c, size_t n);
int memcmp(const void *s1, const void *s2, size_t n);
void *memcpy(void *restrict s1, const void *restrict s2, size_t n);
void *memmove(void *s1, const void *s2, size_t n);
void *memset(void *s, int c, size_t n);
void *memmem(const void *haystack, size_t haystacklen,
     const void *needle, size_t needlelen);
#define __STDC_WANT_LIB_EXT1__ 1
#include <string.h>

errno_t memcpy_s(void *restrict s1, rsize_t s1max,
    const void *restrict s2, rsize_t n);
errno_t memmove_s(void *s1, rsize_t s1max,
    const void *s2, rsize_t n);
errno_t memset_s(void *s, rsize_t smax, int c, rsize_t n);

ISO C++

#include <string.h>

const void *memchr(const void *s, int c, size_t n);
#include <cstring>

void *std::memchr(void *s, int c, size_t n);

Description

These functions operate as efficiently as possible on memory areas (arrays of bytes bounded by a count, not terminated by a null character). They do not check for the overflow of any receiving memory area.

The memccpy() function copies bytes from memory area s2 into s1, stopping after the first occurrence of c (converted to an unsigned char) has been copied, or after n bytes have been copied, whichever comes first. It returns a pointer to the byte after the copy of c in s1, or a null pointer if c was not found in the first n bytes of s2.

The memchr() function returns a pointer to the first occurrence of c (converted to an unsigned char) in the first n bytes (each interpreted as an unsigned char) of memory area s, or a null pointer if c does not occur.

The memcmp() function compares its arguments, looking at the first n bytes (each interpreted as an unsigned char), and returns an integer less than, equal to, or greater than 0, according as s1 is lexicographically less than, equal to, or greater than s2 when taken to be unsigned characters.

The memcpy() function copies n bytes from memory area s2 to s1. It returns s1. If copying takes place between objects that overlap, the behavior is undefined.

The memmove() function copies n bytes from memory area s2 to memory area s1. Copying between objects that overlap will take place correctly. It returns s1.

The memset() function sets the first n bytes in memory area s to the value of c (converted to an unsigned char). It returns s.

The memmem() function locates the start of the first occurrence of the substring needle of length needlelen in the memory area haystack of length haystacklen. It returns a pointer to the start of the substring, or NULL if the substring is not found. If needlelen is zero, haystack is returned. If haystacklen is less than needlelen, NULL is returned.

The memcpy_s(), memmove_s(), and memset_s() functions are part of the C11 bounds checking interfaces specified in the C11 standard, Annex K. Each provide equivalent functionality to the respective memcpy(), memmove_s(), and memset_s() functions, except with differing parameters and return type in order to provide explicit runtime-constraints as defined in the C11 standard. See runtime_constraint_handler(3C) and INCITS/ISO/IEC 9899:2011.

Return Values

If no runtime-constraint violation is detected, the memcpy_s(), memmove_s(), and memset_s() functions return zero. Otherwise they return a non-zero value.

Errors

The memcpy_s() function will fail if:

EINVAL

NULL pointer passed or source and destination overlap.

ERANGE

size argument is invalid, that is, s1max or n is greater than RSIZE_MAX or n is greater than s1max.

The memmove_s() function will fail if:

EINVAL

NULL pointer passed.

ERANGE

size argument is invalid, that is, s1max or n is greater than RSIZE_MAX or n is greater than s1max.

The memset_s() function will fail if:

EINVAL

NULL pointer passed.

ERANGE

size argument is invalid, that is, smax or n is greater than RSIZE_MAX or n is greater than smax.

Usage

Using memcpy() might be faster than using memmove() if the application knows that the objects being copied do not overlap.

Attributes

See attributes(7) for descriptions of the following attributes:

ATTRIBUTE TYPE
ATTRIBUTE VALUE
Interface Stability
Committed
MT-Level
See below
Standard

The memory(), memccpy(), memchr(), memcmp(), memcpy(), memmove(), memset(), and memmem() functions can be used safely in multithreaded applications.

The memcpy_s(), memmove_s(), and memset_s() functions cannot be used safely in a multithreaded application due to the runtime constraint handler. For more information, see the runtime_constraint_handler(3C) man page.

See Also

timingsafe_memcmp(3C), string(3C), attributes(7), standards(7), runtime_constraint_handler(3C)

Notes

Overlap between objects being copied can arise even when their (virtual) address ranges appear to be disjoint; for example, as a result of memory-mapping overlapping portions of the same underlying file, or of attaching the same shared memory segment more than once.