|
|
@ -30,7 +30,7 @@ |
|
|
|
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF |
|
|
|
.\" SUCH DAMAGE. |
|
|
|
.\" |
|
|
|
.\" $OpenBSD: malloc.3,v 1.120 2018/11/21 06:57:04 otto Exp $ |
|
|
|
.\" $OpenBSD: malloc.3,v 1.121 2018/11/21 09:22:58 jmc Exp $ |
|
|
|
.\" |
|
|
|
.Dd $Mdocdate: November 21 2018 $ |
|
|
|
.Dt MALLOC 3 |
|
|
@ -234,6 +234,115 @@ If |
|
|
|
is not a multiple of |
|
|
|
.Fa alignment , |
|
|
|
behavior is undefined. |
|
|
|
.Sh MALLOC OPTIONS |
|
|
|
Upon the first call to the |
|
|
|
.Fn malloc |
|
|
|
family of functions, an initialization sequence inspects the |
|
|
|
value of the |
|
|
|
.Va vm.malloc_conf |
|
|
|
.Xr sysctl 2 , |
|
|
|
next checks the environment for a variable called |
|
|
|
.Ev MALLOC_OPTIONS , |
|
|
|
and finally looks at the global variable |
|
|
|
.Va malloc_options |
|
|
|
in the program. |
|
|
|
Each is scanned for the flags documented below. |
|
|
|
Unless otherwise noted uppercase means on, lowercase means off. |
|
|
|
.Bl -tag -width indent |
|
|
|
.It Cm C |
|
|
|
.Dq Canaries . |
|
|
|
Add canaries at the end of allocations in order to detect |
|
|
|
heap overflows. |
|
|
|
The canary's content is checked when |
|
|
|
.Nm free |
|
|
|
is called. |
|
|
|
If it has been corrupted, the process is aborted. |
|
|
|
.It Cm D |
|
|
|
.Dq Dump . |
|
|
|
.Fn malloc |
|
|
|
will dump statistics to the file |
|
|
|
.Pa ./malloc.out , |
|
|
|
if it already exists, |
|
|
|
at exit. |
|
|
|
This option requires the library to have been compiled with -DMALLOC_STATS in |
|
|
|
order to have any effect. |
|
|
|
.It Cm F |
|
|
|
.Dq Freecheck . |
|
|
|
Enable more extensive double free and use after free detection. |
|
|
|
All chunks in the delayed free list will be checked for double frees. |
|
|
|
Unused pages on the freelist are read and write protected to |
|
|
|
cause a segmentation fault upon access. |
|
|
|
.It Cm G |
|
|
|
.Dq Guard . |
|
|
|
Enable guard pages. |
|
|
|
Each page size or larger allocation is followed by a guard page that will |
|
|
|
cause a segmentation fault upon any access. |
|
|
|
.It Cm J |
|
|
|
.Dq More junking . |
|
|
|
Increase the junk level by one if it is smaller than 2. |
|
|
|
.It Cm j |
|
|
|
.Dq Less junking . |
|
|
|
Decrease the junk level by one if it is larger than 0. |
|
|
|
Junking writes some junk bytes into the area allocated. |
|
|
|
Junk is bytes of 0xdb when allocating; |
|
|
|
freed chunks are filled with 0xdf. |
|
|
|
By default the junk level is 1: after free, |
|
|
|
small chunks are completely junked; |
|
|
|
for pages the first part is junked. |
|
|
|
After a delay, |
|
|
|
the filling pattern is validated and the process is aborted if the pattern |
|
|
|
was modified. |
|
|
|
For junk level 2, junking is done on allocation as well and without size |
|
|
|
restrictions. |
|
|
|
If the junk level is zero, no junking is performed. |
|
|
|
.It Cm R |
|
|
|
.Dq realloc . |
|
|
|
Always reallocate when |
|
|
|
.Fn realloc |
|
|
|
is called, even if the initial allocation was big enough. |
|
|
|
.\".Pp |
|
|
|
.\".It Cm U |
|
|
|
.\".Dq utrace . |
|
|
|
.\"Generate entries for |
|
|
|
.\".Xr ktrace 1 |
|
|
|
.\"for all operations. |
|
|
|
.\"Consult the source for this one. |
|
|
|
.It Cm S |
|
|
|
Enable all options suitable for security auditing. |
|
|
|
.It Cm U |
|
|
|
.Dq Free unmap . |
|
|
|
Enable use after free protection for larger allocations. |
|
|
|
Unused pages on the freelist are read and write protected to |
|
|
|
cause a segmentation fault upon access. |
|
|
|
.It Cm X |
|
|
|
.Dq xmalloc . |
|
|
|
Rather than return failure, |
|
|
|
.Xr abort 3 |
|
|
|
the program with a diagnostic message on stderr. |
|
|
|
It is the intention that this option be set at compile time by |
|
|
|
including in the source: |
|
|
|
.Bd -literal -offset indent |
|
|
|
extern char *malloc_options; |
|
|
|
malloc_options = "X"; |
|
|
|
.Ed |
|
|
|
.Pp |
|
|
|
Note that this will cause code that is supposed to handle |
|
|
|
out-of-memory conditions gracefully to abort instead. |
|
|
|
.It Cm < |
|
|
|
.Dq Halve the cache size . |
|
|
|
Decrease the size of the free page cache by a factor of two. |
|
|
|
.It Cm > |
|
|
|
.Dq Double the cache size . |
|
|
|
Increase the size of the free page cache by a factor of two. |
|
|
|
.El |
|
|
|
.Pp |
|
|
|
If a program changes behavior if any of these options (except |
|
|
|
.Cm X ) |
|
|
|
are used, |
|
|
|
it is buggy. |
|
|
|
.Pp |
|
|
|
The default number of free pages cached is 64 per malloc pool. |
|
|
|
Multi-threaded programs use multiple pools. |
|
|
|
.Sh RETURN VALUES |
|
|
|
Upon successful completion, the allocation functions |
|
|
|
return a pointer to the allocated space; otherwise, |
|
|
@ -404,8 +513,7 @@ Deallocation of such an object should be done by calling |
|
|
|
.Sh ENVIRONMENT |
|
|
|
.Bl -tag -width "MALLOC_OPTIONS" |
|
|
|
.It Ev MALLOC_OPTIONS |
|
|
|
String of flags documented in |
|
|
|
.Xr malloc.conf 5 . |
|
|
|
String of option flags. |
|
|
|
.El |
|
|
|
.Sh EXAMPLES |
|
|
|
If |
|
|
@ -460,6 +568,11 @@ or at the cost of initialization: |
|
|
|
if ((p = calloc(num, size)) == NULL) |
|
|
|
err(1, NULL); |
|
|
|
.Ed |
|
|
|
.Pp |
|
|
|
Set a systemwide reduction of the cache to a quarter of the |
|
|
|
default size and use guard pages: |
|
|
|
.Pp |
|
|
|
.Dl # sysctl vm.malloc_conf='G<<' |
|
|
|
.Sh DIAGNOSTICS |
|
|
|
If any of the functions detect an error condition, |
|
|
|
a message will be printed to file descriptor |
|
|
@ -525,11 +638,10 @@ consult sources and/or wizards. |
|
|
|
.Xr brk 2 , |
|
|
|
.Xr mmap 2 , |
|
|
|
.Xr munmap 2 , |
|
|
|
.Xr sysctl 2 , |
|
|
|
.Xr alloca 3 , |
|
|
|
.Xr getpagesize 3 , |
|
|
|
.Xr posix_memalign 3 , |
|
|
|
.Xr sysconf 3 , |
|
|
|
.Xr malloc.conf 5 |
|
|
|
.Xr posix_memalign 3 |
|
|
|
.Sh STANDARDS |
|
|
|
The |
|
|
|
.Fn malloc , |
|
|
|