Fincer
/
openntpd-openbsd
mirror of https://github.com/Fincer/openntpd-openbsd


.\"

.\" Copyright (c) 1980, 1991, 1993

.\"	The Regents of the University of California.  All rights reserved.

.\"

.\" This code is derived from software contributed to Berkeley by

.\" the American National Standards Committee X3, on Information

.\" Processing Systems.

.\"

.\" Redistribution and use in source and binary forms, with or without

.\" modification, are permitted provided that the following conditions

.\" are met:

.\" 1. Redistributions of source code must retain the above copyright

.\"    notice, this list of conditions and the following disclaimer.

.\" 2. Redistributions in binary form must reproduce the above copyright

.\"    notice, this list of conditions and the following disclaimer in the

.\"    documentation and/or other materials provided with the distribution.

.\" 3. Neither the name of the University nor the names of its contributors

.\"    may be used to endorse or promote products derived from this software

.\"    without specific prior written permission.

.\"

.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND

.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE

.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE

.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE

.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL

.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS

.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)

.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT

.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY

.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF

.\" SUCH DAMAGE.

.\"

.\"	$OpenBSD: malloc.3,v 1.110 2017/04/10 05:45:02 otto Exp $

.\"

.Dd $Mdocdate: April 10 2017 $

.Dt MALLOC 3

.Os

.Sh NAME

.Nm malloc ,

.Nm calloc ,

.Nm realloc ,

.Nm free

.Nm reallocarray ,

.Nm recallocarray ,

.Nm freezero ,

.Nd memory allocation and deallocation

.Sh SYNOPSIS

.In stdlib.h

.Ft void *

.Fn malloc "size_t size"

.Ft void *

.Fn calloc "size_t nmemb" "size_t size"

.Ft void *

.Fn realloc "void *ptr" "size_t size"

.Ft void

.Fn free "void *ptr"

.Ft void *

.Fn reallocarray "void *ptr" "size_t nmemb" "size_t size"

.Ft void *

.Fn recallocarray "void *ptr" "size_t oldnmemb" "size_t nmemb" "size_t size"

.Ft void

.Fn freezero "void *ptr" "size_t size"

.Vt char *malloc_options ;

.Sh DESCRIPTION

The standard functions

.Fn malloc ,

.Fn calloc ,

and

.Fn realloc

allocate memory space.

The

.Fn malloc

function allocates uninitialized space for an object of

the specified

.Fa size .

.Fn malloc

maintains multiple lists of free blocks according to size, allocating

space from the appropriate list.

The allocated space is suitably aligned (after possible pointer coercion) for

storage of any type of object.

.Pp

The

.Fn calloc

function allocates space for an array of

.Fa nmemb

objects, each of the specified

.Fa size .

The space is initialized to zero.

.Pp

The

.Fn realloc

function changes the size of the object pointed to by

.Fa ptr

to

.Fa size

bytes and returns a pointer to the (possibly moved) object.

The contents of the object are unchanged up to the lesser

of the new and old sizes.

If the new size is larger, the value of the newly allocated portion

of the object is indeterminate and uninitialized.

If the space cannot be allocated, the object

pointed to by

.Fa ptr

is unchanged.

If

.Fa ptr

is

.Dv NULL ,

.Fn realloc

behaves like

.Fn malloc

and allocates a new object.

.Pp

The

.Fn free

function causes the space pointed to by

.Fa ptr

to be either placed on a list of free blocks to make it available for future

allocation or, when appropiate, to be returned to the kernel using

.Xr munmap 2 .

If

.Fa ptr

is a

.Dv NULL

pointer, no action occurs.

If

.Fa ptr

was previously freed by

.Fn free

or a reallocation function,

the behavior is undefined and the double free is a security concern.

.Pp

Designed for safe allocation of arrays,

the

.Fn reallocarray

function is similar to

.Fn realloc

except it operates on

.Fa nmemb

members of size

.Fa size

and checks for integer overflow in the calculation

.Fa nmemb

*

.Fa size .

.Pp

Used for the allocation of memory holding sensitive data,

the

.Fn recallocarray

function is similar to

.Fn reallocarray

except it ensures newly allocated memory is cleared similar to

.Xr calloc 3 .

Memory that becomes unallocated while shrinking or moving existing

allocations is explicitly discarded (meaning, pages of memory

are disposed via

.Xr munmap 2 ,

and smaller allocations are cleared with

.Xr explicit_bzero 3 ) .

If

.Fa ptr

is a

.Dv NULL

pointer,

.Fa oldnmemb

is ignored and the call is equivalent to

.Fn calloc .

If

.Fa ptr

is not a

.Dv NULL

pointer,

.Fa oldnmemb

must be a value such that

.Fa oldnmemb

*

.Fa size

is the size of the earlier allocation that returned

.Fa ptr ,

otherwise the behaviour is undefined.

.Pp

The

.Fn freezero

function is similar to the

.Fn free

function except it ensures the memory being deallocated is explicitly

discarded.

If

.Fa ptr

is

.Dv NULL ,

no action occurs.

If

.Fa ptr

is not

.Dv NULL ,

the

.Fa size

argument must be the size of the earlier allocation that returned

.Fa ptr ,

otherwise the behaviour is undefined.

.Sh RETURN VALUES

Upon successful completion, the allocation functions

return a pointer to the allocated space; otherwise, a

.Dv NULL

pointer is returned and

.Va errno

is set to

.Er ENOMEM .

.Pp

If

.Fa nmemb

or

.Fa size

is equal to 0, a unique pointer to an access protected,

zero sized object is returned.

Access via this pointer will generate a

.Dv SIGSEGV

exception.

.Pp

If multiplying

.Fa nmemb

and

.Fa size

results in integer overflow,

.Fn calloc ,

.Fn reallocarray

and

.Fn recallocarray

return

.Dv NULL

and set

.Va errno

to

.Er ENOMEM .

.Pp

If

.Fa ptr

is not NULL and multiplying

.Fa oldnmemb

and

.Fa size

results in integer overflow

.Fn recallocarray

returns

.Dv NULL

and sets

.Va errno

to

.Er EINVAL .

.Sh IDIOMS

Consider

.Fn calloc

or the extensions

.Fn reallocarray

and

.Fn recallocarray

when there is multiplication in the

.Fa size

argument of

.Fn malloc

or

.Fn realloc .

For example, avoid this common idiom as it may lead to integer overflow:

.Bd -literal -offset indent

if ((p = malloc(num * size)) == NULL)

	err(1, NULL);

.Ed

.Pp

A drop-in replacement is the

.Ox

extension

.Fn reallocarray :

.Bd -literal -offset indent

if ((p = reallocarray(NULL, num, size)) == NULL)

	err(1, NULL);

.Ed

.Pp

Alternatively,

.Fn calloc

may be used at the cost of initialization overhead.

.Pp

When using

.Fn realloc ,

be careful to avoid the following idiom:

.Bd -literal -offset indent

size += 50;

if ((p = realloc(p, size)) == NULL)

	return (NULL);

.Ed

.Pp

Do not adjust the variable describing how much memory has been allocated

until the allocation has been successful.

This can cause aberrant program behavior if the incorrect size value is used.

In most cases, the above sample will also result in a leak of memory.

As stated earlier, a return value of

.Dv NULL

indicates that the old object still remains allocated.

Better code looks like this:

.Bd -literal -offset indent

newsize = size + 50;

if ((newp = realloc(p, newsize)) == NULL) {

	free(p);

	p = NULL;

	size = 0;

	return (NULL);

}

p = newp;

size = newsize;

.Ed

.Pp

As with

.Fn malloc ,

it is important to ensure the new size value will not overflow;

i.e. avoid allocations like the following:

.Bd -literal -offset indent

if ((newp = realloc(p, num * size)) == NULL) {

	...

.Ed

.Pp

Instead, use

.Fn reallocarray :

.Bd -literal -offset indent

if ((newp = reallocarray(p, num, size)) == NULL) {

	...

.Ed

.Pp

Calling

.Fn realloc

with a

.Dv NULL

.Fa ptr

is equivalent to calling

.Fn malloc .

Instead of this idiom:

.Bd -literal -offset indent

if (p == NULL)

	newp = malloc(newsize);

else

	newp = realloc(p, newsize);

.Ed

.Pp

Use the following:

.Bd -literal -offset indent

newp = realloc(p, newsize);

.Ed

.Pp

The

.Fn recallocarray

function should be used for resizing objects containing sensitive data like

keys.

To avoid leaking information,

it guarantees memory is cleared before placing it on the internal free list.

Deallocation of such an object should be done by calling

.Fn freezero .

.Sh ENVIRONMENT

.Bl -tag -width "/etc/malloc.conf"

.It Ev MALLOC_OPTIONS

String of flags documented in

.Xr malloc.conf 5 .

.El

.Sh FILES

.Bl -tag -width "/etc/malloc.conf"

.It Pa /etc/malloc.conf

Symbolic link to filename containing option flags.

.El

.Sh EXAMPLES

If

.Fn malloc

must be used with multiplication, be sure to test for overflow:

.Bd -literal -offset indent

size_t num, size;

\&...


/* Check for size_t overflow */

if (size && num > SIZE_MAX / size)

	errc(1, EOVERFLOW, "overflow");


if ((p = malloc(num * size)) == NULL)

	err(1, NULL);

.Ed

.Pp

The above test is not sufficient in all cases.

For example, multiplying ints requires a different set of checks:

.Bd -literal -offset indent

int num, size;

\&...


/* Avoid invalid requests */

if (size < 0 || num < 0)

	errc(1, EOVERFLOW, "overflow");


/* Check for signed int overflow */

if (size && num > INT_MAX / size)

	errc(1, EOVERFLOW, "overflow");


if ((p = malloc(num * size)) == NULL)

	err(1, NULL);

.Ed

.Pp

Assuming the implementation checks for integer overflow as

.Ox

does, it is much easier to use

.Fn calloc ,

.Fn reallocarray ,

or

.Fn recallocarray .

.Pp

The above examples could be simplified to:

.Bd -literal -offset indent

if ((p = reallocarray(NULL, num, size)) == NULL)

	err(1, NULL);

.Ed

.Pp

or at the cost of initialization:

.Bd -literal -offset indent

if ((p = calloc(num, size)) == NULL)

	err(1, NULL);

.Ed

.Sh DIAGNOSTICS

If any of the functions detect an error condition,

a message will be printed to file descriptor

2 (not using stdio).

Errors will result in the process being aborted.

.Pp

Here is a brief description of the error messages and what they mean:

.Bl -tag -width Ds

.It Dq out of memory

If the

.Cm X

option is specified it is an error for the allocation functions

to return

.Dv NULL .

.It Dq malloc init mmap failed

This is a rather weird condition that is most likely to indicate a

seriously overloaded system or a ulimit restriction.

.It Dq bogus pointer (double free?)

An attempt to

.Fn free

or

reallocate an unallocated pointer was made.

.It Dq chunk is already free

There was an attempt to free a chunk that had already been freed.

.It Dq use after free

A chunk has been modified after it was freed.

.It Dq modified chunk-pointer

The pointer passed to

.Fn free

or a reallocation function has been modified.

.It Dq chunk canary corrupted address offset@length

A byte after the requested size has been overwritten,

indicating a heap overflow.

The offset at which corruption was detected is printed before the @,

and the requested length of the allocation after the @.

.It Dq recorded old size oldsize != size

.Fn recallocarray

has detected that the given old size does not equal the recorded size in its

meta data.

Enabling option

.Cm C

allows

.Fn recallocarray

to catch more of these cases.

.It Dq recursive call

An attempt was made to call recursively into these functions, i.e., from a

signal handler.

This behavior is not supported.

In particular, signal handlers should

.Em not

use any of the

.Fn malloc

functions nor utilize any other functions which may call

.Fn malloc

(e.g.,

.Xr stdio 3

routines).

.It Dq unknown char in MALLOC_OPTIONS

We found something we didn't understand.

.It any other error

.Fn malloc

detected an internal error;

consult sources and/or wizards.

.El

.Sh SEE ALSO

.Xr brk 2 ,

.Xr mmap 2 ,

.Xr munmap 2 ,

.Xr alloca 3 ,

.Xr getpagesize 3 ,

.Xr posix_memalign 3 ,

.Xr sysconf 3 ,

.Xr malloc.conf 5

.Sh STANDARDS

The

.Fn malloc ,

.Fn calloc ,

.Fn realloc ,

and

.Fn free

functions conform to

.St -ansiC .

.Pp

If

.Fa nmemb

or

.Fa size

are 0, the return value is implementation defined;

other conforming implementations may return

.Dv NULL

in this case.

.Pp

The

.Ev MALLOC_OPTIONS

environment variable, the file

.Pa /etc/malloc.conf ,

and the

.Sx DIAGNOSTICS

output are extensions to the standard.

.Sh HISTORY

A

.Fn free

internal kernel function and a predecessor to

.Fn malloc ,

.Fn alloc ,

first appeared in

.At v1 .

C library functions

.Fn alloc

and

.Fn free

appeared in

.At v6 .

The functions

.Fn malloc ,

.Fn calloc ,

and

.Fn realloc

first appeared in

.At v7 .

.Pp

A new implementation by Chris Kingsley was introduced in

.Bx 4.2 ,

followed by a complete rewrite by Poul-Henning Kamp which appeared in

.Fx 2.2

and was included in

.Ox 2.0 .

These implementations were all

.Xr sbrk 2

based.

In

.Ox 3.8 ,

Thierry Deval rewrote

.Nm

to use the

.Xr mmap 2

system call,

making the page addresses returned by

.Nm

random.

A rewrite by Otto Moerbeek introducing a new central data structure and more

randomization appeared in

.Ox 4.4 .

.Pp

The

.Fn reallocarray

function appeared in

.Ox 5.6 .

The

.Fn recallocarray

function appeared in

.Ox 6.1 .

The

.Fn freezero

function appeared in

.Ox 6.2 .

.Sh CAVEATS

When using

.Fn malloc ,

be wary of signed integer and

.Vt size_t

overflow especially when there is multiplication in the

.Fa size

argument.

.Pp

Signed integer overflow will cause undefined behavior which compilers

typically handle by wrapping back around to negative numbers.

Depending on the input, this can result in allocating more or less

memory than intended.

.Pp

An unsigned overflow has defined behavior which will wrap back around and

return less memory than intended.

.Pp

A signed or unsigned integer overflow is a

.Em security

risk if less memory is returned than intended.

Subsequent code may corrupt the heap by writing beyond the memory that was

allocated.

An attacker may be able to leverage this heap corruption to execute arbitrary

code.

.Pp

Consider using

.Fn calloc ,

.Fn reallocarray

or

.Fn recallocarray

instead of using multiplication in

.Fn malloc

and

.Fn realloc

to avoid these problems on

								.Ox .