xref: /illumos-gate/usr/src/man/man3c/memory.3c (revision bbf215553c7233fbab8a0afdf1fac74c44781867)

.\"
.\" Copyright (c) 2014, Joyent, Inc.
.\" Copyright (c) 2009, Sun Microsystems, Inc.  All Rights Reserved.
.\" Copyright 1989 AT&T
.\" Copyright 2021 Oxide Computer Company
.\"
.\" The contents of this file are subject to the terms of the
.\" Common Development and Distribution License (the "License").
.\" You may not use this file except in compliance with the License.
.\"
.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
.\" or http://www.opensolaris.org/os/licensing.
.\" See the License for the specific language governing permissions
.\" and limitations under the License.
.\"
.\" When distributing Covered Code, include this CDDL HEADER in each
.\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
.\" If applicable, add the following below this CDDL HEADER, with the
.\" fields enclosed by brackets "[]" replaced with your own identifying
.\" information: Portions Copyright [yyyy] [name of copyright owner]
.\"
.Dd January 25, 2022
.Dt MEMORY 3C
.Os
.Sh NAME
.Nm memory ,
.Nm memccpy ,
.Nm memchr ,
.Nm memcmp ,
.Nm memcpy ,
.Nm memmem ,
.Nm memmove ,
.Nm memrchr ,
.Nm memset
.Nd memory operations
.Sh SYNOPSIS
.In string.h
.Ft "void *"
.Fo memccpy
.Fa "void *restrict s1"
.Fa "const void *restrict s2"
.Fa "int c"
.Fa "size_t n"
.Fc
.Ft "void *"
.Fo memchr
.Fa "void *s"
.Fa "int c"
.Fa "size_t n"
.Fc
.Ft int
.Fo memcmp
.Fa "const void *s1"
.Fa "const void *s2"
.Fa "size_t n"
.Fc
.Ft "void *"
.Fo memcpy
.Fa "void *restrict s1"
.Fa "const void *restrict s2"
.Fa "size_t n"
.Fc
.Ft "void *"
.Fo memmem
.Fa "const void *l"
.Fa "size_t l_len"
.Fa "const void *s"
.Fa "size_t s_len"
.Fc
.Ft "void *"
.Fo memmove
.Fa "void *s1"
.Fa "const void *s2"
.Fa "size_t n"
.Fc
.Ft "void *"
.Fo memrchr
.Fa "void *s"
.Fa "int c"
.Fa "size_t n"
.Fc
.Ft "void *"
.Fo memset
.Fa "void *s"
.Fa "int c"
.Fa "size_t n"
.Fc
.Sh 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.
.Pp
The
.Fn memccpy
function copies bytes from memory area
.Fa s2
into
.Fa s1 ,
stopping after the first occurrence of
.Fa c
.Po
converted to an
.Vt unsigned char
.Pc
has been copied, or after
.Fa n
bytes have been copied, whichever comes first.
It returns a pointer to the byte after the copy of
.Fa c
in
.Fa s1 ,
or a
.Dv NULL
pointer if
.Fa c
was not found in the first
.Fa n
bytes of
.Fa s2 .
.Pp
The
.Fn memchr
function returns a pointer to the first occurrence of
.Fa c
.Po
converted to an
.Vt unsigned char
.Pc
in the first
.Fa n
bytes
.Po
each interpreted as an
.Vt unsigned char
.Pc
of memory area
.Fa s ,
or a
.Dv NULL
pointer if
.Fa c
does not occur.
.Pp
The
.Fn memrchr
function behaves similarly to the
.Fn memchr
function, except that the memory area is searched in reverse from the
last byte.
.Pp
The
.Fn memcmp
function compares its arguments, looking at the first
.Fa n
bytes
.Po
each interpreted as an
.Vt unsigned char
.Pc ,
and returns an integer less than, equal to, or greater than 0, according as
.Fa s1
is less than, equal to, or greater than
.Fa s2
when taken to be unsigned characters.
.Pp
The
.Fn memcpy
function copies
.Fa n
bytes from memory area
.Fa s2
to
.Fa s1
It returns
.Fa s1 .
If copying takes place between objects that overlap, the behavior is undefined.
In such cases, use
.Fn memmove
instead.
.Pp
The
.Fn memmem
function searches for the
.Fa s_len
long byte pattern
.Fa s
in the memory region starting at
.Fa l
for
.Fa l_len
bytes.
If a match is found, a pointer to the starting location in
.Fa l
is returned.
If no match is found,
.Fa l_len
is zero,
.Fa s_len
is zero, or
.Fa l_len
is less than
.Fa s_len
then a
.Dv NULL
pointer is return.
.Pp
The
.Fn memmove
function copies
.Fa n
bytes from memory area
.Fa s2
to memory area
.Fa s1 .
Copying between objects that overlap will take place correctly.
It returns
.Fa s1 .
.Pp
The
.Fn memset
function sets the first
.Fa n
bytes in memory area
.Fa s
to the value of
.Fa c
.Po
converted to an
.Vt unsigned char
.Pc .
It returns
.Fa s .
.Sh USAGE
Using
.Fn memcpy
might be faster than using
.Fn memmove
if the
application knows that the objects being copied do not overlap.
.Sh INTERFACE STABILITY
.Sy Committed
.Sh MT-LEVEL
.Sy MT-Safe
.Sh SEE ALSO
.Xr string 3C ,
.Xr attributes 7 ,
.Xr standards 7
.Sh NOTES
Overlap between objects being copied can arise even when their
.Pq 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.