diff options
Diffstat (limited to 'usr/src/man/man3malloc')
| -rw-r--r-- | usr/src/man/man3malloc/Makefile | 67 | ||||
| -rw-r--r-- | usr/src/man/man3malloc/bsdmalloc.3malloc | 117 | ||||
| -rw-r--r-- | usr/src/man/man3malloc/malloc.3malloc | 279 | ||||
| -rw-r--r-- | usr/src/man/man3malloc/mapmalloc.3malloc | 116 | ||||
| -rw-r--r-- | usr/src/man/man3malloc/mtmalloc.3malloc | 241 | ||||
| -rw-r--r-- | usr/src/man/man3malloc/umem_alloc.3malloc | 442 | ||||
| -rw-r--r-- | usr/src/man/man3malloc/umem_cache_create.3malloc | 719 | ||||
| -rw-r--r-- | usr/src/man/man3malloc/umem_debug.3malloc | 232 | ||||
| -rw-r--r-- | usr/src/man/man3malloc/watchmalloc.3malloc | 234 |
9 files changed, 2447 insertions, 0 deletions
diff --git a/usr/src/man/man3malloc/Makefile b/usr/src/man/man3malloc/Makefile new file mode 100644 index 0000000000..d01a7e232f --- /dev/null +++ b/usr/src/man/man3malloc/Makefile @@ -0,0 +1,67 @@ +# +# This file and its contents are supplied under the terms of the +# Common Development and Distribution License ("CDDL"), version 1.0. +# You may only use this file in accordance with the terms of version +# 1.0 of the CDDL. +# +# A full copy of the text of the CDDL should have accompanied this +# source. A copy of the CDDL is also available via the Internet +# at http://www.illumos.org/license/CDDL. +# + +# Copyright 2011, Richard Lowe + +include ../../Makefile.master + +MANSECT = 3malloc + +MANFILES = bsdmalloc.3malloc \ + malloc.3malloc \ + mapmalloc.3malloc \ + mtmalloc.3malloc \ + umem_alloc.3malloc \ + umem_cache_create.3malloc \ + umem_debug.3malloc \ + watchmalloc.3malloc + +MANSOFILES = calloc.3malloc \ + free.3malloc \ + mallinfo.3malloc \ + mallocctl.3malloc \ + mallopt.3malloc \ + memalign.3malloc \ + realloc.3malloc \ + umem_cache_alloc.3malloc \ + umem_cache_destroy.3malloc \ + umem_cache_free.3malloc \ + umem_free.3malloc \ + umem_nofail_callback.3malloc \ + umem_zalloc.3malloc \ + valloc.3malloc + +MANFILES += $(MANSOFILES) + +calloc.3malloc := SOSRC = man3malloc/malloc.3malloc +free.3malloc := SOSRC = man3malloc/malloc.3malloc +mallinfo.3malloc := SOSRC = man3malloc/malloc.3malloc +mallopt.3malloc := SOSRC = man3malloc/malloc.3malloc +memalign.3malloc := SOSRC = man3malloc/malloc.3malloc +realloc.3malloc := SOSRC = man3malloc/malloc.3malloc +valloc.3malloc := SOSRC = man3malloc/malloc.3malloc + +mallocctl.3malloc := SOSRC = man3malloc/mtmalloc.3malloc + +umem_free.3malloc := SOSRC = man3malloc/umem_alloc.3malloc +umem_nofail_callback.3malloc := SOSRC = man3malloc/umem_alloc.3malloc +umem_zalloc.3malloc := SOSRC = man3malloc/umem_alloc.3malloc + +umem_cache_alloc.3malloc := SOSRC = man3malloc/umem_cache_create.3malloc +umem_cache_destroy.3malloc := SOSRC = man3malloc/umem_cache_create.3malloc +umem_cache_free.3malloc := SOSRC = man3malloc/umem_cache_create.3malloc + +.KEEP_STATE: + +include ../Makefile.man + +install: $(ROOTMANFILES) + diff --git a/usr/src/man/man3malloc/bsdmalloc.3malloc b/usr/src/man/man3malloc/bsdmalloc.3malloc new file mode 100644 index 0000000000..4b00266f4d --- /dev/null +++ b/usr/src/man/man3malloc/bsdmalloc.3malloc @@ -0,0 +1,117 @@ +'\" te +.\" Copyright (c) 2005, Sun Microsystems, Inc. All Rights Reserved. +.\" 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] +.TH bsdmalloc 3MALLOC "21 Mar 2005" "SunOS 5.11" "Memory Allocation Library Functions" +.SH NAME +bsdmalloc \- memory allocator +.SH SYNOPSIS +.LP +.nf +\fBcc\fR [ \fIflag\fR ... ] \fIfile\fR ... \fB-lbsdmalloc\fR [ \fIlibrary\fR ... ] + +\fBchar *\fR\fBmalloc\fR(\fB\fR\fIsize\fRunsigned \fIsize\fR; +.fi + +.LP +.nf +\fBint\fR \fBfree\fR(\fB\fR \fIptr\fRchar *\fIptr\fR; +.fi + +.LP +.nf +\fBchar *\fR\fBrealloc\fR(\fB\fR \fIptr\fR, \fB\fR\fIsize\fRchar *\fIptr\fR; +unsigned \fIsize\fR; +.fi + +.SH DESCRIPTION +.sp +.LP +These routines provide a general-purpose memory allocation package. They +maintain a table of free blocks for efficient allocation and coalescing of free +storage. When there is no suitable space already free, the allocation routines +call \fBsbrk\fR(2) to get more memory from the system. Each of the allocation +routines returns a pointer to space suitably aligned for storage of any type +of object. Each returns a null pointer if the request cannot be completed. +.sp +.LP +The \fBmalloc()\fR function returns a pointer to a block of at least +\fIsize\fR bytes, which is appropriately aligned. +.sp +.LP +The \fBfree()\fR function releases a previously allocated block. Its argument +is a pointer to a block previously allocated by \fBmalloc()\fR or +\fBrealloc()\fR. The \fBfree()\fR function does not set \fBerrno\fR. +.sp +.LP +The \fBrealloc()\fR function changes the size of the block pointed to by +\fIptr\fR to \fIsize\fR bytes and returns a pointer to the (possibly moved) +block. The contents will be unchanged up to the lesser of the new and old +sizes. If the new size of the block requires movement of the block, the space +for the previous instantiation of the block is freed. If the new size is +larger, the contents of the newly allocated portion of the block are +unspecified. If \fIptr\fR is \fINULL\fR, \fBrealloc()\fR behaves like +\fBmalloc()\fR for the specified size. If \fIsize\fR is 0 and \fIptr\fR is not +a null pointer, the space pointed to is freed. +.SH RETURN VALUES +.sp +.LP +The \fBmalloc()\fR and \fBrealloc()\fR functions return a null pointer if there +is not enough available memory. They return a non-null pointer if \fIsize\fR +is 0. These pointers should not be dereferenced. When \fBrealloc()\fR returns +\fINULL\fR, the block pointed to by \fIptr\fR is left intact. Always cast the +value returned by \fBmalloc()\fR and \fBrealloc()\fR. +.SH ERRORS +.sp +.LP +If \fBmalloc()\fR or \fBrealloc()\fR returns unsuccessfully, \fBerrno\fR will +be set to indicate the following: +.sp +.ne 2 +.mk +.na +\fB\fBENOMEM\fR\fR +.ad +.RS 10n +.rt +\fIsize\fR bytes of memory cannot be allocated because it exceeds the physical +limits of the system. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEAGAIN\fR\fR +.ad +.RS 10n +.rt +There is not enough memory available at this point in time to allocate +\fIsize\fR bytes of memory; but the application could try again later. +.RE + +.SH USAGE +.sp +.LP +Using \fBrealloc()\fR with a block freed before the most recent call to +\fBmalloc()\fR or \fBrealloc()\fR results in an error. +.sp +.LP +Comparative features of the various allocation libraries can be found in the +\fBumem_alloc\fR(3MALLOC) manual page. +.SH SEE ALSO +.sp +.LP +\fBbrk\fR(2), \fBmalloc\fR(3C), \fBmalloc\fR(3MALLOC), +\fBmapmalloc\fR(3MALLOC), \fBumem_alloc\fR(3MALLOC) +.SH WARNINGS +.sp +.LP +Use of \fBlibbsdmalloc\fR renders an application non-SCD compliant. +.sp +.LP +The \fBlibbsdmalloc\fR routines are incompatible with the memory allocation +routines in the standard C-library (libc): \fBmalloc\fR(3C), \fBalloca\fR(3C), +\fBcalloc\fR(3C), \fBfree\fR(3C), \fBmemalign\fR(3C), \fBrealloc\fR(3C), and +\fBvalloc\fR(3C). diff --git a/usr/src/man/man3malloc/malloc.3malloc b/usr/src/man/man3malloc/malloc.3malloc new file mode 100644 index 0000000000..91220b879c --- /dev/null +++ b/usr/src/man/man3malloc/malloc.3malloc @@ -0,0 +1,279 @@ +'\" te +.\" Copyright 1989 AT&T. Copyright (c) 2005, Sun Microsystems, Inc. All Rights Reserved. +.\" 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] +.TH malloc 3MALLOC "11 May 2005" "SunOS 5.11" "Memory Allocation Library Functions" +.SH NAME +malloc, free, memalign, realloc, valloc, calloc, mallopt, mallinfo \- memory +allocator +.SH SYNOPSIS +.LP +.nf +\fBcc\fR [ \fIflag\fR ... ] \fIfile\fR ... \fB-lmalloc\fR [ \fIlibrary\fR ... ] +#include <stdlib.h> + +\fBvoid *\fR\fBmalloc\fR(\fBsize_t\fR \fIsize\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBfree\fR(\fBvoid *\fR\fIptr\fR); +.fi + +.LP +.nf +\fBvoid *\fR\fBmemalign\fR(\fBsize_t\fR \fIalignment\fR, \fBsize_t\fR \fIsize\fR); +.fi + +.LP +.nf +\fBvoid *\fR\fBrealloc\fR(\fBvoid *\fR\fIptr\fR, \fBsize_t\fR \fIsize\fR); +.fi + +.LP +.nf +\fBvoid *\fR\fBvalloc\fR(\fBsize_t\fR \fIsize\fR); +.fi + +.LP +.nf +\fBvoid *\fR\fBcalloc\fR(\fBsize_t\fR \fInelem\fR, \fBsize_t\fR \fIelsize\fR); +.fi + +.LP +.nf +#include <malloc.h> + +\fBint\fR \fBmallopt\fR(\fBint\fR \fIcmd\fR, \fBint\fR \fIvalue\fR); +.fi + +.LP +.nf +\fBstruct mallinfo\fR \fBmallinfo\fR(\fBvoid\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBmalloc()\fR and \fBfree()\fR functions provide a simple general-purpose +memory allocation package. +.sp +.LP +The \fBmalloc()\fR function returns a pointer to a block of at least \fIsize\fR +bytes suitably aligned for any use. +.sp +.LP +The argument to \fBfree()\fR is a pointer to a block previously allocated by +\fBmalloc()\fR. After \fBfree()\fR is performed, this space is made available +for further allocation, and its contents have been destroyed. See +\fBmallopt()\fR below for a way to change this behavior. If \fIptr\fR is a null +pointer, no action occurs. +.sp +.LP +Undefined results occur if the space assigned by \fBmalloc()\fR is overrun or +if some random number is handed to \fBfree()\fR. +.sp +.LP +The \fBfree()\fR function does not set \fBerrno\fR. +.sp +.LP +The \fBmemalign()\fR function allocates \fIsize\fR bytes on a specified +alignment boundary and returns a pointer to the allocated block. The value of +the returned address is guaranteed to be an even multiple of \fIalignment\fR. +The value of \fIalignment\fR must be a power of two and must be greater than or +equal to the size of a word. +.sp +.LP +The \fBrealloc()\fR function changes the size of the block pointed to by +\fIptr\fR to \fIsize\fR bytes and returns a pointer to the (possibly moved) +block. The contents will be unchanged up to the lesser of the new and old +sizes. If the new size of the block requires movement of the block, the space +for the previous instantiation of the block is freed. If the new size is +larger, the contents of the newly allocated portion of the block are +unspecified. If \fIptr\fR is \fINULL\fR, \fBrealloc()\fR behaves like +\fBmalloc()\fR for the specified size. If \fIsize\fR is 0 and \fIptr\fR is not +a null pointer, the space pointed to is freed. +.sp +.LP +The \fBvalloc()\fR function has the same effect as \fBmalloc()\fR, except that +the allocated memory will be aligned to a multiple of the value returned by +\fBsysconf\fR(\fB_SC_PAGESIZE\fR). +.sp +.LP +The \fBcalloc()\fR function allocates space for an array of \fInelem\fR +elements of size \fIelsize\fR. The space is initialized to zeros. +.sp +.LP +The \fBmallopt()\fR function provides for control over the allocation +algorithm. The available values for \fIcmd\fR are: +.sp +.ne 2 +.mk +.na +\fB\fBM_MXFAST\fR\fR +.ad +.RS 12n +.rt +Set \fImaxfast\fR to \fIvalue\fR. The algorithm allocates all blocks below the +size of \fImaxfast\fR in large groups and then doles them out very quickly. The +default value for \fImaxfast\fR is 24. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBM_NLBLKS\fR\fR +.ad +.RS 12n +.rt +Set \fInumlblks\fR to \fIvalue\fR. The above mentioned ``large groups'' each +contain \fInumlblks\fR blocks. \fInumlblks\fR must be greater than 0. The +default value for \fInumlblks\fR is 100. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBM_GRAIN\fR\fR +.ad +.RS 12n +.rt +Set \fIgrain\fR to \fIvalue\fR. The sizes of all blocks smaller than +\fImaxfast\fR are considered to be rounded up to the nearest multiple of +\fIgrain\fR. \fIgrain\fR must be greater than 0. The default value of +\fIgrain\fR is the smallest number of bytes that will allow alignment of any +data type. Value will be rounded up to a multiple of the default when +\fIgrain\fR is set. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBM_KEEP\fR\fR +.ad +.RS 12n +.rt +Preserve data in a freed block until the next \fBmalloc()\fR, \fBrealloc()\fR, +or \fBcalloc()\fR. This option is provided only for compatibility with the old +version of \fBmalloc()\fR, and it is not recommended. +.RE + +.sp +.LP +These values are defined in the \fB<malloc.h>\fR header. +.sp +.LP +The \fBmallopt()\fR function can be called repeatedly, but cannot be called +after the first small block is allocated. +.sp +.LP +The \fBmallinfo()\fR function provides instrumentation describing space usage. +It returns the \fBmallinfo\fR structure with the following members: +.sp +.in +2 +.nf +unsigned long arena; /* total space in arena */ +unsigned long ordblks; /* number of ordinary blocks */ +unsigned long smblks; /* number of small blocks */ +unsigned long hblkhd; /* space in holding block headers */ +unsigned long hblks; /* number of holding blocks */ +unsigned long usmblks; /* space in small blocks in use */ +unsigned long fsmblks; /* space in free small blocks */ +unsigned long uordblks; /* space in ordinary blocks in use */ +unsigned long fordblks; /* space in free ordinary blocks */ +unsigned long keepcost; /* space penalty if keep option */ + /* is used */ +.fi +.in -2 + +.sp +.LP +The \fBmallinfo\fR structure is defined in the <\fBmalloc.h\fR> header. +.sp +.LP +Each of the allocation routines returns a pointer to space suitably aligned +(after possible pointer coercion) for storage of any type of object. +.SH RETURN VALUES +.sp +.LP +The \fBmalloc()\fR, \fBmemalign()\fR, \fBrealloc()\fR, \fBvalloc()\fR, and +\fBcalloc()\fR functions return a null pointer if there is not enough available +memory. When \fBrealloc()\fR returns \fINULL\fR, the block pointed to by +\fIptr\fR is left intact. If \fIsize\fR, \fInelem\fR, or \fIelsize\fR is 0, +either a null pointer or a unique pointer that can be passed to \fBfree()\fR is +returned. If \fBmallopt()\fR is called after any allocation or if \fIcmd\fR or +\fIvalue\fR are invalid, a non-zero value is returned. Otherwise, it returns 0. +.SH ERRORS +.sp +.LP +If \fBmalloc()\fR, \fBcalloc()\fR, or \fBrealloc()\fR returns unsuccessfully, +\fBerrno\fR is set to indicate the error: +.sp +.ne 2 +.mk +.na +\fB\fBENOMEM\fR\fR +.ad +.RS 10n +.rt +\fIsize\fR bytes of memory exceeds the physical limits of your system, and +cannot be allocated. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEAGAIN\fR\fR +.ad +.RS 10n +.rt +There is not enough memory available at this point in time to allocate +\fIsize\fR bytes of memory; but the application could try again later. +.RE + +.SH USAGE +.sp +.LP +Unlike \fBmalloc\fR(3C), this package does not preserve the contents of a block +when it is freed, unless the \fBM_KEEP\fR option of \fBmallopt()\fR is used. +.sp +.LP +Undocumented features of \fBmalloc\fR(3C) have not been duplicated. +.sp +.LP +Function prototypes for \fBmalloc()\fR, \fBrealloc()\fR, \fBcalloc()\fR, and +\fBfree()\fR are also defined in the <\fBmalloc.h\fR> header for compatibility +with old applications. New applications should include <\fBstdlib.h\fR> to +access the prototypes for these functions. +.sp +.LP +Comparative features of the various allocation libraries can be found in the +\fBumem_alloc\fR(3MALLOC) manual page. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +MT-LevelSafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBbrk\fR(2), \fBbsdmalloc\fR(3MALLOC), \fBlibmtmalloc\fR(3LIB), +\fBmalloc\fR(3C), \fBmapmalloc\fR(3MALLOC), \fBmtmalloc\fR(3MALLOC), +\fBumem_alloc\fR(3MALLOC), \fBwatchmalloc\fR(3MALLOC), \fBattributes\fR(5) diff --git a/usr/src/man/man3malloc/mapmalloc.3malloc b/usr/src/man/man3malloc/mapmalloc.3malloc new file mode 100644 index 0000000000..ec857e48d4 --- /dev/null +++ b/usr/src/man/man3malloc/mapmalloc.3malloc @@ -0,0 +1,116 @@ +'\" te +.\" Copyright 1989 AT&T. Copyright (c) 2004, Sun Microsystems, Inc. All Rights Reserved. +.\" 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] +.TH mapmalloc 3MALLOC "20 Feb 2004" "SunOS 5.11" "Memory Allocation Library Functions" +.SH NAME +mapmalloc \- memory allocator +.SH SYNOPSIS +.LP +.nf +\fBcc\fR [ \fIflag\fR ... ] \fIfile\fR ... \fB-lmapmalloc\fR [ \fIlibrary\fR ... ] +#include <stdlib.h> + +\fBvoid *\fR\fBmalloc\fR(\fBsize_t\fR \fIsize\fR); +.fi + +.LP +.nf +\fBvoid *\fR\fBcalloc\fR(\fBsize_t\fR \fInelem\fR, \fBsize_t\fR \fIelsize\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBfree\fR(\fBvoid *\fR \fIptr\fR); +.fi + +.LP +.nf +\fBvoid *\fR\fBrealloc\fR(\fBvoid *\fR\fIptr\fR, \fBsize_t\fR \fIsize\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The collection of \fBmalloc\fR functions in this library use \fBmmap\fR(2) +instead of \fBsbrk\fR(2) for acquiring new heap space. The functions in this +library are intended to be used only if necessary, when applications must call +\fBsbrk()\fR, but need to call other library routines that might call +\fBmalloc\fR. The algorithms used by these functions are not sophisticated. +There is no reclaiming of memory. +.sp +.LP +The \fBmalloc()\fR and \fBfree()\fR functions provide a simple general-purpose +memory allocation package. +.sp +.LP +The \fBmalloc()\fR function returns a pointer to a block of at least \fIsize\fR +bytes suitably aligned for any use. +.sp +.LP +The argument to \fBfree()\fR is a pointer to a block previously allocated by +\fBmalloc()\fR, \fBcalloc()\fR or \fBrealloc()\fR. If \fIptr\fR is a +\fINULL\fR pointer, no action occurs. +.sp +.LP +Undefined results will occur if the space assigned by \fBmalloc()\fR is overrun +or if some random number is handed to \fBfree()\fR. +.sp +.LP +The \fBcalloc()\fR function allocates space for an array of \fInelem\fR +elements of size \fIelsize\fR. The space is initialized to zeros. +.sp +.LP +The \fBrealloc()\fR function changes the size of the block pointed to by +\fIptr\fR to \fIsize\fR bytes and returns a pointer to the (possibly moved) +block. The contents will be unchanged up to the lesser of the new and old +sizes. If the new size of the block requires movement of the block, the space +for the previous instantiation of the block is freed. If the new size is +larger, the contents of the newly allocated portion of the block are +unspecified. If \fIptr\fR is \fINULL\fR, \fBrealloc()\fR behaves like +\fBmalloc()\fR for the specified size. If \fIsize\fR is 0 and \fIptr\fR is not +a null pointer, the space pointed to is freed. +.sp +.LP +Each of the allocation functions returns a pointer to space suitably aligned +(after possible pointer coercion) for storage of any type of object. +.sp +.LP +The \fBmalloc()\fR and \fBrealloc()\fR functions will fail if there is not +enough available memory. +.sp +.LP +Entry points for \fBmalloc_debug()\fR, \fBmallocmap()\fR, \fBmallopt()\fR, +\fBmallinfo()\fR, \fBmemalign()\fR, and \fBvalloc()\fR are empty routines, and +are provided only to protect the user from mixing \fBmalloc()\fR functions from +different implementations. +.SH RETURN VALUES +.sp +.LP +If there is no available memory, \fBmalloc()\fR, \fBrealloc()\fR, and +\fBcalloc()\fR return a null pointer. When \fBrealloc()\fR returns \fINULL\fR, +the block pointed to by \fIptr\fR is left intact. If \fIsize\fR, \fInelem\fR, +or \fIelsize\fR is 0, a unique pointer to the arena is returned. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +MT-LevelSafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBbrk\fR(2), \fBgetrlimit\fR(2), \fBmmap\fR(2), \fBrealloc\fR(3C), +\fBmalloc\fR(3MALLOC), \fBattributes\fR(5) diff --git a/usr/src/man/man3malloc/mtmalloc.3malloc b/usr/src/man/man3malloc/mtmalloc.3malloc new file mode 100644 index 0000000000..4a4ab93b51 --- /dev/null +++ b/usr/src/man/man3malloc/mtmalloc.3malloc @@ -0,0 +1,241 @@ +'\" te +.\" Copyright 1989 AT&T. Copyright (c) 2004, Sun Microsystems, Inc. All Rights Reserved. +.\" 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] +.TH mtmalloc 3MALLOC "21 Mar 2005" "SunOS 5.11" "Memory Allocation Library Functions" +.SH NAME +mtmalloc, mallocctl \- MT hot memory allocator +.SH SYNOPSIS +.LP +.nf +#include <mtmalloc.h> +cc -o a.out -lthread -lmtmalloc + +\fBvoid *\fR\fBmalloc\fR(\fBsize_t\fR \fIsize\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBfree\fR(\fBvoid *\fR\fIptr\fR); +.fi + +.LP +.nf +\fBvoid *\fR\fBmemalign\fR(\fBsize_t\fR \fIalignment\fR, \fBsize_t\fR \fIsize\fR); +.fi + +.LP +.nf +\fBvoid *\fR\fBrealloc\fR(\fBvoid *\fR\fIptr\fR, \fBsize_t\fR \fIsize\fR); +.fi + +.LP +.nf +\fBvoid *\fR\fBvalloc\fR(\fBsize_t\fR \fIsize\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBmallocctl\fR(\fBint\fR \fIcmd\fR, \fBlong\fR \fIvalue\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBmalloc()\fR and \fBfree()\fR functions provide a simple general-purpose +memory allocation package that is suitable for use in high performance +multithreaded applications. The suggested use of this library is in +multithreaded applications; it can be used for single threaded applications, +but there is no advantage in doing so. This library cannot be dynamically +loaded with \fBdlopen\fR(3C) during runtime because there must be only one +manager of the process heap. +.sp +.LP +The \fBmalloc()\fR function returns a pointer to a block of at least \fIsize\fR +bytes suitably aligned for any use. +.sp +.LP +The argument to \fBfree()\fR is a pointer to a block previously allocated by +\fBmalloc()\fR or \fBrealloc()\fR. After \fBfree()\fR is performed this space +is available for further allocation. If \fIptr\fR is a null pointer, no action +occurs. The \fBfree()\fR function does not set \fBerrno\fR. +.sp +.LP +Undefined results will occur if the space assigned by \fBmalloc()\fR is overrun +or if a random number is handed to \fBfree()\fR. A freed pointer that is passed +to \fBfree()\fR will send a \fBSIGABRT\fR signal to the calling process. This +behavior is controlled by \fBmallocctl()\fR. +.sp +.LP +The \fBmemalign()\fR function allocates \fIsize\fR bytes on a specified +alignment boundary and returns a pointer to the allocated block. The value of +the returned address is guaranteed to be an even multiple of \fIalignment\fR. +Note that the value of \fIalignment\fR must be a power of two, and must be +greater than or equal to the size of a word. +.sp +.LP +The \fBrealloc()\fR function changes the size of the block pointed to by +\fIptr\fR to \fIsize\fR bytes and returns a pointer to the (possibly moved) +block. The contents will be unchanged up to the lesser of the new and old +sizes. If the new size of the block requires movement of the block, the space +for the previous instantiation of the block is freed. If the new size is +larger, the contents of the newly allocated portion of the block are +unspecified. If \fIptr\fR is \fINULL\fR, \fBrealloc()\fR behaves like +\fBmalloc()\fR for the specified size. If \fIsize\fR is 0 and \fIptr\fR is not +a null pointer, the space pointed to is freed. +.sp +.LP +The \fBvalloc()\fR function has the same effect as \fBmalloc()\fR, except that +the allocated memory will be aligned to a multiple of the value returned by +\fBsysconf\fR(\fB_SC_PAGESIZE\fR). +.sp +.LP +After possible pointer coercion, each allocation routine returns a pointer to +a space that is suitably aligned for storage of any type of object. +.sp +.LP +The \fBmalloc()\fR, \fBrealloc()\fR, \fBmemalign()\fR, and \fBvalloc()\fR +functions will fail if there is not enough available memory. +.sp +.LP +The \fBmallocctl()\fR function controls the behavior of the \fBmalloc\fR +library. The options fall into two general classes, debugging options and +performance options. +.sp +.ne 2 +.mk +.na +\fB\fBMTDOUBLEFREE\fR\fR +.ad +.RS 18n +.rt +Allows double \fBfree\fR of a pointer. Setting \fIvalue\fR to \fB1\fR means +yes and \fB0\fR means no. The default behavior of double \fBfree\fR results in +a core dump. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBMTDEBUGPATTERN\fR\fR +.ad +.RS 18n +.rt +Writes misaligned data into the buffer after \fBfree()\fR. When the buffer is +reallocated, the contents are verified to ensure that there was no access to +the buffer after the \fBfree\fR. If the buffer has been dirtied, a +\fBSIGABRT\fR signal is delivered to the process. Setting \fIvalue\fR to +\fB1\fR means yes and \fB0\fR means no. The default behavior is to \fInot\fR +write misaligned data. The pattern used is \fB0xdeadbeef\fR. Use of this +option results in a performance penalty. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBMTINITBUFFER\fR\fR +.ad +.RS 18n +.rt +Writes misaligned data into the newly allocated buffer. This option is useful +for detecting some accesses before initialization. Setting \fIvalue\fR to +\fB1\fR means yes and \fB0\fR means no. The default behavior is to \fInot\fR +write misaligned data to the newly allocated buffer. The pattern used is +\fB0xbaddcafe\fR. Use of this option results in a performance penalty. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBMTCHUNKSIZE\fR\fR +.ad +.RS 18n +.rt +This option changes the size of allocated memory when a pool has exhausted all +available memory in the buffer. Increasing this value allocates more memory +for the application. A substantial performance gain can occur because the +library makes fewer calls to the OS for more memory. Acceptable number +\fIvalue\fRs are between \fB9\fR and \fB256\fR. The default value is \fB9\fR. +This value is multiplied by 8192. +.RE + +.SH RETURN VALUES +.sp +.LP +If there is no available memory, \fBmalloc()\fR, \fBrealloc()\fR, +\fBmemalign()\fR, and \fBvalloc()\fR return a null pointer. When +\fBrealloc()\fR is called with \fIsize\fR > 0 and returns \fINULL\fR, the block +pointed to by \fIptr\fR is left intact. If \fIsize\fR, \fInelem\fR, or +\fIelsize\fR is 0, either a null pointer or a unique pointer that can be passed +to \fBfree()\fR is returned. +.sp +.LP +If \fBmalloc()\fR or \fBrealloc()\fR returns unsuccessfully, \fBerrno\fR will +be set to indicate the error. +.SH ERRORS +.sp +.LP +The \fBmalloc()\fR and \fBrealloc()\fR functions will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBENOMEM\fR\fR +.ad +.RS 10n +.rt +The physical limits of the system are exceeded by \fIsize\fR bytes of memory +which cannot be allocated. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEAGAIN\fR\fR +.ad +.RS 10n +.rt +There is not enough memory available to allocate \fIsize\fR bytes of memory; +but the application could try again later. +.RE + +.SH USAGE +.sp +.LP +Comparative features of the various allocation libraries can be found in the +\fBumem_alloc\fR(3MALLOC) manual page. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +MT-LevelSafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBbrk\fR(2), \fBgetrlimit\fR(2), \fBbsdmalloc\fR(3MALLOC), \fBdlopen\fR(3C), +\fBmalloc\fR(3C), \fBmalloc\fR(3MALLOC), \fBmapmalloc\fR(3MALLOC), +\fBsignal.h\fR(3HEAD), \fBumem_alloc\fR(3MALLOC), \fBwatchmalloc\fR(3MALLOC), +\fBattributes\fR(5) +.SH WARNINGS +.sp +.LP +Undefined results will occur if the size requested for a block of memory +exceeds the maximum size of a process's heap. This information may be obtained +using \fBgetrlimit()\fR. diff --git a/usr/src/man/man3malloc/umem_alloc.3malloc b/usr/src/man/man3malloc/umem_alloc.3malloc new file mode 100644 index 0000000000..0f70a40182 --- /dev/null +++ b/usr/src/man/man3malloc/umem_alloc.3malloc @@ -0,0 +1,442 @@ +'\" te +.\" Copyright (c) 2008 Sun Microsystems, Inc. All Rights Reserved. +.\" 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] +.TH umem_alloc 3MALLOC "24 Mar 2008" "SunOS 5.11" "Memory Allocation Library Functions" +.SH NAME +umem_alloc, umem_zalloc, umem_free, umem_nofail_callback \- fast, scalable +memory allocation +.SH SYNOPSIS +.LP +.nf +cc [ \fIflag \&.\|.\|.\fR ] \fIfile\fR\&.\|.\|. \fB-lumem\fR [ \fIlibrary \&.\|.\|.\fR ] +#include <umem.h> + +\fBvoid *\fR\fBumem_alloc\fR(\fBsize_t\fR \fIsize\fR, \fBint\fR \fIflags\fR); +.fi + +.LP +.nf +\fBvoid *\fR\fBumem_zalloc\fR(\fBsize_t\fR \fIsize\fR, \fBint\fR \fIflags\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBumem_free\fR(\fBvoid *\fR\fIbuf\fR, \fBsize_t\fR \fIsize\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBumem_nofail_callback\fR(\fB(int (*\fR\fIcallback\fR)(void)); +.fi + +.LP +.nf +\fBvoid *\fR\fBmalloc\fR(\fBsize_t\fR \fIsize\fR); +.fi + +.LP +.nf +\fBvoid *\fR\fBcalloc\fR(\fBsize_t\fR \fInelem\fR, \fBsize_t\fR \fIelsize\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBfree\fR(\fBvoid *\fR\fIptr\fR); +.fi + +.LP +.nf +\fBvoid *\fR\fBmemalign\fR(\fBsize_t\fR \fIalignment\fR, \fBsize_t\fR \fIsize\fR); +.fi + +.LP +.nf +\fBvoid *\fR\fBrealloc\fR(\fBvoid *\fR\fIptr\fR, \fBsize_t\fR \fIsize\fR); +.fi + +.LP +.nf +\fBvoid *\fR\fBvalloc\fR(\fBsize_t\fR \fIsize\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBumem_alloc()\fR function returns a pointer to a block of \fIsize\fR +bytes suitably aligned for any variable type. The initial contents of memory +allocated using \fBumem_alloc()\fR is undefined. The \fIflags\fR argument +determines the behavior of \fBumem_alloc()\fR if it is unable to fulfill the +request. The \fIflags\fR argument can take the following values: +.sp +.ne 2 +.mk +.na +\fB\fBUMEM_DEFAULT\fR\fR +.ad +.RS 16n +.rt +Return \fINULL\fR on failure. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBUMEM_NOFAIL\fR\fR +.ad +.RS 16n +.rt +Call an optional \fIcallback\fR (set with \fBumem_nofail_callback()\fR) on +failure. The \fIcallback\fR takes no arguments and can finish by: +.RS +4 +.TP +.ie t \(bu +.el o +returning \fBUMEM_CALLBACK_RETRY\fR, in which case the allocation will be +retried. If the allocation fails, the callback will be invoked again. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +returning \fBUMEM_CALLBACK_EXIT\fR(\fIstatus\fR), in which case \fBexit\fR(2) +is invoked with \fIstatus\fR as its argument. The \fBexit()\fR function is +called only once. If multiple threads return from the \fBUMEM_NOFAIL\fR +callback with \fBUMEM_CALLBACK_EXIT\fR(\fIstatus\fR), one will call +\fBexit()\fR while the other blocks until \fBexit()\fR terminates the program. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +invoking a context-changing function (\fBsetcontext\fR(2)) or a non-local jump +(\fBlongjmp\fR(3C) or \fBsiglongjmp\fR(3C), or ending the current thread of +control (\fBthr_exit\fR(3C) or \fBpthread_exit\fR(3C). The application is +responsible for any necessary cleanup. The state of \fBlibumem\fR remains +consistent. +.RE +If no callback has been set or the callback has been set to \fINULL\fR, +\fBumem_alloc\fR(..., \fBUMEM_NOFAIL\fR) behaves as though the callback +returned \fBUMEM_CALLBACK_EXIT\fR(255). +.sp +The \fBlibumem\fR library can call callbacks from any place that a +\fBUMEM_NOFAIL\fR allocation is issued. In multithreaded applications, +callbacks are expected to perform their own concurrency management. +.RE + +.sp +.LP +The function call \fBumem_alloc\fR(0, \fIflag\fR) always returns \fINULL\fR. +The function call \fBumem_free\fR(\fINULL\fR, 0) is allowed. +.sp +.LP +The \fBumem_zalloc()\fR function has the same semantics as \fBumem_alloc()\fR, +but the block of memory is initialized to zeros before it is returned. +.sp +.LP +The \fBumem_free()\fR function frees blocks previously allocated using +\fBumem_alloc()\fR and \fBumem_zalloc()\fR. The buffer address and size must +exactly match the original allocation. Memory must not be returned piecemeal. +.sp +.LP +The \fBumem_nofail_callback()\fR function sets the process-wide UMEM_NOFAIL +callback. See the description of UMEM_NOFAIL for more information. +.sp +.LP +The \fBmalloc()\fR, \fBcalloc()\fR, \fBfree()\fR, \fBmemalign()\fR, +\fBrealloc()\fR, and \fBvalloc()\fR functions are as described in +\fBmalloc\fR(3C). The \fBlibumem\fR library provides these functions for +backwards-compatibility with the standard functions. +.SH ENVIRONMENT VARIABLES +.sp +.LP +See \fBumem_debug\fR(3MALLOC) for environment variables that effect the +debugging features of the \fBlibumem\fR library. +.sp +.ne 2 +.mk +.na +\fB\fBUMEM_OPTIONS\fR\fR +.ad +.RS 16n +.rt +Contains a list of comma-separated options. Unrecognized options are ignored. +The options that are supported are: +.sp +.ne 2 +.mk +.na +\fB\fBbackend\fR=\fBsbrk\fR\fR +.ad +.br +.na +\fB\fBbackend\fR=\fBmmap\fR\fR +.ad +.RS 16n +.rt +Set the underlying function used to allocate memory. This option can be set to +\fBsbrk\fR (the default) for an \fBsbrk\fR(2)-based source or \fBmmap\fR for an +\fBmmap\fR(2)-based source. If set to a value that is not supported, \fBsbrk\fR +will be used. +.RE + +.RE + +.SH EXAMPLES +.LP +\fBExample 1 \fRUsing the \fBumem_alloc()\fR function. +.sp +.in +2 +.nf +#include <stdio.h> +#include <umem.h> +\&... +char *buf = umem_alloc(1024, UMEM_DEFAULT); + +if (buf == NULL) { + fprintf(stderr, "out of memory\en"); + return (1); +} +/* cannot assume anything about buf's contents */ +\&... +umem_free(buf, 1024); +\&... +.fi +.in -2 + +.LP +\fBExample 2 \fRUsing the \fBumem_zalloc()\fR function +.sp +.in +2 +.nf +#include <stdio.h> +#include <umem.h> +\&... +char *buf = umem_zalloc(1024, UMEM_DEFAULT); + +if (buf == NULL) { + fprintf(stderr, "out of memory\en"); + return (1); +} +/* buf contains zeros */ +\&... +umem_free(buf, 1024); +\&... +.fi +.in -2 + +.LP +\fBExample 3 \fRUsing UMEM_NOFAIL +.sp +.in +2 +.nf +#include <stdlib.h> +#include <stdio.h> +#include <umem.h> + +/* + * Note that the allocation code below does not have to + * check for umem_alloc() returning NULL + */ +int +my_failure_handler(void) +{ + (void) fprintf(stderr, "out of memory\en"); + return (UMEM_CALLBACK_EXIT(255)); +} +\&... +umem_nofail_callback(my_failure_handler); +\&... +int i; +char *buf[100]; + +for (i = 0; i < 100; i++) + buf[i] = umem_alloc(1024 * 1024, UMEM_NOFAIL); +\&... +for (i = 0; i < 100; i++) + umem_free(buf[i], 1024 * 1024); +\&... +.fi +.in -2 + +.LP +\fBExample 4 \fRUsing UMEM_NOFAIL in a multithreaded application +.sp +.in +2 +.nf +#define _REENTRANT +#include <thread.h> +#include <stdio.h> +#include <umem.h> + +void * +start_func(void *the_arg) +{ + int *info = (int *)the_arg; + char *buf = umem_alloc(1024 * 1024, UMEM_NOFAIL); + + /* does not need to check for buf == NULL */ + buf[0] = 0; + ... + /* + * if there were other UMEM_NOFAIL allocations, + * we would need to arrange for buf to be + * umem_free()ed upon failure. + */ + ... + umem_free(buf, 1024 * 1024); + return (the_arg); +} +\&... +int +my_failure_handler(void) +{ + /* terminate the current thread with status NULL */ + thr_exit(NULL); +} +\&... +umem_nofail_callback(my_failure_handler); +\&... +int my_arg; + +thread_t tid; +void *status; + +(void) thr_create(NULL, NULL, start_func, &my_arg, 0, + NULL); +\&... +while (thr_join(0, &tid, &status) != 0) + ; + +if (status == NULL) { + (void) fprintf(stderr, "thread %d ran out of memory\en", + tid); +} +\&... +.fi +.in -2 + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityCommitted +_ +MT-LevelMT-Safe +_ +StandardSee below. +.TE + +.sp +.LP +For \fBmalloc()\fR, \fBcalloc()\fR, \fBfree()\fR, \fBrealloc()\fR, and +\fBvalloc()\fR, see \fBstandards\fR(5). +.SH SEE ALSO +.sp +.LP +\fBexit\fR(2), \fBmmap\fR(2), \fBsbrk\fR(2), \fBbsdmalloc\fR(3MALLOC), +\fBlibumem\fR(3LIB), \fBlongjmp\fR(3C), \fBmalloc\fR(3C), +\fBmalloc\fR(3MALLOC), \fBmapmalloc\fR(3MALLOC), \fBpthread_exit\fR(3C), +\fBthr_exit\fR(3C), \fBumem_cache_create\fR(3MALLOC), +\fBumem_debug\fR(3MALLOC), \fBwatchmalloc\fR(3MALLOC), \fBattributes\fR(5), +\fBstandards\fR(5) +.sp +.LP +\fISolaris Modular Debugger Guide\fR +.SH WARNINGS +.sp +.LP +Any of the following can cause undefined results: +.RS +4 +.TP +.ie t \(bu +.el o +Passing a pointer returned from \fBumem_alloc()\fR or \fBumem_zalloc()\fR to +\fBfree()\fR or \fBrealloc()\fR. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +Passing a pointer returned from \fBmalloc()\fR, \fBcalloc()\fR, \fBvalloc()\fR, +\fBmemalign()\fR, or \fBrealloc()\fR to \fBumem_free()\fR. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +Writing past the end of a buffer allocated using \fBumem_alloc()\fR or +\fBumem_zalloc()\fR +.RE +.RS +4 +.TP +.ie t \(bu +.el o +Performing \fBUMEM_NOFAIL\fR allocations from an \fBatexit\fR(3C) handler. +.RE +.sp +.LP +If the \fBUMEM_NOFAIL\fR callback performs \fBUMEM_NOFAIL\fR allocations, +infinite recursion can occur. +.SH NOTES +.sp +.LP +The following list compares the features of the \fBmalloc\fR(3C), +\fBbsdmalloc\fR(3MALLOC), \fBmalloc\fR(3MALLOC), \fBmtmalloc\fR(3MALLOC) , and +the \fBlibumem\fR functions. +.RS +4 +.TP +.ie t \(bu +.el o +The \fBmalloc\fR(3C), \fBbsdmalloc\fR(3MALLOC), and \fBmalloc\fR(3MALLOC) +functions have no support for concurrency. The \fBlibumem\fR and +\fBmtmalloc\fR(3MALLOC) functions support concurrent allocations. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +The \fBbsdmalloc\fR(3MALLOC) functions afford better performance but are +space-inefficient. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +The \fBmalloc\fR(3MALLOC) functions are space-efficient but have slower +performance. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +The standard, fully SCD-compliant \fBmalloc\fR(3C) functions are a trade-off +between performance and space-efficiency. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +The \fBmtmalloc\fR(3MALLOC) functions provide fast, concurrent \fBmalloc()\fR +implementations that are not space-efficient. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +The \fBlibumem\fR functions provide a fast, concurrent allocation +implementation that in most cases is more space-efficient than +\fBmtmalloc\fR(3MALLOC). +.RE diff --git a/usr/src/man/man3malloc/umem_cache_create.3malloc b/usr/src/man/man3malloc/umem_cache_create.3malloc new file mode 100644 index 0000000000..b76bbc7837 --- /dev/null +++ b/usr/src/man/man3malloc/umem_cache_create.3malloc @@ -0,0 +1,719 @@ +'\" te +.\" Copyright (c) 2009, Sun Microsystems, Inc. All Rights Reserved. +.\" 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] +.TH umem_cache_create 3MALLOC "24 Mar 2008" "SunOS 5.11" "Memory Allocation Library Functions" +.SH NAME +umem_cache_create, umem_cache_destroy, umem_cache_alloc, umem_cache_free \- +allocation cache manipulation +.SH SYNOPSIS +.LP +.nf +cc [ \fIflag \&.\|.\|.\fR ] \fIfile\fR\&.\|.\|. \fB-lumem\fR [ \fIlibrary \&.\|.\|.\fR ] +#include <umem.h> + +\fBumem_cache_t *\fR\fBumem_cache_create\fR(\fBchar *\fR\fIdebug_name\fR, \fBsize_t\fR \fIbufsize\fR, + \fBsize_t\fR \fIalign\fR, \fBumem_constructor_t *\fR\fIconstructor\fR, + \fBumem_destructor_t *\fR\fIdestructor\fR, \fBumem_reclaim_t *\fR\fIreclaim\fR, + \fBvoid *\fR\fIcallback_data\fR, \fBvmem_t *\fR\fIsource\fR, \fBint\fR \fIcflags\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBumem_cache_destroy\fR(\fBumem_cache_t *\fR\fIcache\fR); +.fi + +.LP +.nf +\fBvoid *\fR\fBumem_cache_alloc\fR(\fBumem_cache_t *\fR\fIcache\fR, \fBint\fR \fIflags\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBumem_cache_free\fR(\fBumem_cache_t *\fR\fIcache\fR, \fBvoid *\fR\fIbuffer\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +These functions create, destroy, and use an "object cache" An object cache is +a collection of buffers of a single size, with optional content caching enabled +by the use of callbacks (see \fBCache Callbacks\fR). Object caches are +MT-Safe. Multiple allocations and freeing of memory from different threads can +proceed simultaneously. Object caches are faster and use less space per buffer +than \fBmalloc\fR(3MALLOC) and \fBumem_alloc\fR(3MALLOC). For more information +about object caching, see "The Slab Allocator: An Object-Caching Kernel Memory +Allocator" and "Magazines and vmem: Extending the Slab Allocator to Many CPUs +and Arbitrary Resources". +.sp +.LP +The \fBumem_cache_create()\fR function creates object caches. Once a cache has +been created, objects can be requested from and returned to the cache using +\fBumem_cache_alloc()\fR and \fBumem_cache_free()\fR, respectively. A cache +with no outstanding buffers can be destroyed with \fBumem_cache_destroy()\fR. +.SS "Creating and Destroying Caches" +.sp +.LP +The \fBumem_cache_create()\fR function creates a cache of objects and takes as +arguments the following: +.sp +.ne 2 +.mk +.na +\fB\fIdebug_name\fR\fR +.ad +.RS 17n +.rt +A human-readable name for debugging purposes. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIbufsize\fR\fR +.ad +.RS 17n +.rt +The size, in bytes, of the buffers in this cache. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIalign\fR\fR +.ad +.RS 17n +.rt +The minimum alignment required for buffers in this cache. This parameter must +be a power of 2. If 0, it is replaced with the minimum required alignment for +the current architecture. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIconstructor\fR\fR +.ad +.RS 17n +.rt +The callback to construct an object. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIdestructor\fR\fR +.ad +.RS 17n +.rt +The callback to destroy an object. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIreclaim\fR\fR +.ad +.RS 17n +.rt +The callback to reclaim objects. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIcallback_data\fR\fR +.ad +.RS 17n +.rt +An opaque pointer passed to the callbacks. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIsource\fR\fR +.ad +.RS 17n +.rt +This parameter must be \fINULL\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIcflags\fR\fR +.ad +.RS 17n +.rt +This parameter must be either 0 or \fBUMC_NODEBUG\fR. If \fBUMC_NODEBUG\fR, all +debugging features are disabled for this cache. See \fBumem_debug\fR(3MALLOC). +.RE + +.sp +.LP +Each cache can have up to three associated callbacks: +.sp +.in +2 +.nf +int constructor(void *buffer, void *callback_data, int flags); +void destructor(void *buffer, void *callback_data); +void reclaim(void *callback_data); +.fi +.in -2 + +.sp +.LP +The \fIcallback_data\fR argument is always equal to the value passed to +\fBumem_cache_create()\fR, thereby allowing a client to use the same callback +functions for multiple caches, but with customized behavior. +.sp +.LP +The reclaim callback is called when the umem function is requesting more memory +from the operating system. This callback can be used by clients who retain +objects longer than they are strictly needed (for example, caching non-active +state). A typical reclaim callback might return to the cache ten per cent of +the unneeded buffers. +.sp +.LP +The constructor and destructor callbacks enable the management of buffers with +the constructed state. The constructor takes as arguments a buffer with +undefined contents, some callback data, and the flags to use for any +allocations. This callback should transform the buffer into the constructed +state. +.sp +.LP +The destructor callback takes as an argument a constructed object and prepares +it for return to the general pool of memory. The destructor should undo any +state that the constructor created. For debugging, the destructor can also +check that the buffer is in the constructed state, to catch incorrectly freed +buffers. See \fBumem_debug\fR(3MALLOC) for further information on debugging +support. +.sp +.LP +The \fBumem_cache_destroy()\fR function destroys an object cache. If the cache +has any outstanding allocations, the behavior is undefined. +.SS "Allocating Objects" +.sp +.LP +The \fBumem_cache_alloc()\fR function takes as arguments: +.sp +.ne 2 +.mk +.na +\fB\fIcache\fR\fR +.ad +.RS 9n +.rt +a cache pointer +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIflags\fR\fR +.ad +.RS 9n +.rt +flags that determine the behavior if \fBumem_cache_alloc()\fR is unable to +fulfill the allocation request +.RE + +.sp +.LP +If successful, \fBumem_cache_alloc()\fR returns a pointer to the beginning of +an object of \fIbufsize\fR length. +.sp +.LP +There are three cases to consider: +.RS +4 +.TP +.ie t \(bu +.el o +A new buffer needed to be allocated. If the cache was created with a +constructor, it is applied to the buffer and the resulting object is returned. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +The object cache was able to use a previously freed buffer. If the cache was +created with a constructor, the object is returned unchanged from when it was +freed. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +The allocation of a new buffer failed. The \fIflags\fR argument determines the +behavior: +.RS + +.sp +.ne 2 +.mk +.na +\fB\fBUMEM_DEFAULT\fR\fR +.ad +.RS 16n +.rt +The \fBumem_cache_alloc()\fR function returns \fINULL\fR if the allocation +fails. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBUMEM_NOFAIL\fR\fR +.ad +.RS 16n +.rt +The \fBumem_cache_alloc()\fR function cannot return \fINULL\fR. A callback is +used to determine what action occurs. See \fBumem_alloc\fR(3MALLOC) for more +information. +.RE + +.RE + +.RE +.SS "Freeing Objects" +.sp +.LP +The \fBumem_cache_free()\fR function takes as arguments: +.sp +.ne 2 +.mk +.na +\fB\fIcache\fR\fR +.ad +.RS 9n +.rt +a cache pointer +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIbuf\fR\fR +.ad +.RS 9n +.rt +a pointer previously returned from \fBumem_cache_alloc()\fR. This argument must +not be \fINULL\fR. +.RE + +.sp +.LP +If the cache was created with a constructor callback, the object must be +returned to the constructed state before it is freed. +.sp +.LP +Undefined behavior results if an object is freed multiple times, if an object +is modified after it is freed, or if an object is freed to a cache other than +the one from which it was allocated. +.SS "Caches with Constructors" +.sp +.LP +When a constructor callback is in use, there is essentially a contract between +the cache and its clients. The cache guarantees that all objects returned from +\fBumem_cache_alloc()\fR will be in the constructed state, and the client +guarantees that it will return the object to the constructed state before +handing it to \fBumem_cache_free()\fR. +.SH RETURN VALUES +.sp +.LP +Upon failure, the \fBumem_cache_create()\fR function returns a null pointer. +.SH ERRORS +.sp +.LP +The \fBumem_cache_create()\fR function will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEAGAIN\fR\fR +.ad +.RS 10n +.rt +There is not enough memory available to allocate the cache data structure. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +The \fIdebug_name\fR argument is \fINULL\fR, the \fIalign\fR argument is not a +power of two or is larger than the system pagesize, or the \fIbufsize\fR +argument is 0. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOMEM\fR\fR +.ad +.RS 10n +.rt +The \fBlibumem\fR library could not be initialized, or the \fIbufsize\fR +argument is too large and its use would cause integer overflow to occur. +.RE + +.SH EXAMPLES +.LP +\fBExample 1 \fRUse a fixed-size structure with no constructor callback. +.sp +.in +2 +.nf +#include <umem.h> + +typedef struct my_obj { + long my_data1; +} my_obj_t; + +/* + * my_objs can be freed at any time. The contents of + * my_data1 is undefined at allocation time. + */ + +umem_cache_t *my_obj_cache; + +\&... +my_obj_cache = umem_cache_create("my_obj", sizeof (my_obj_t), + 0, NULL, NULL, NULL, NULL, NULL, 0); +\&... +my_obj_t *cur = umem_cache_alloc(my_obj_cache, UMEM_DEFAULT); +\&... +/* use cur */ +\&... +umem_cache_free(my_obj_cache, cur); +\&... +.fi +.in -2 + +.LP +\fBExample 2 \fRUse an object with a mutex. +.sp +.in +2 +.nf +#define _REENTRANT +#include <synch.h> +#include <umem.h> + +typedef struct my_obj { + mutex_t my_mutex; + long my_data; +} my_obj_t; + +/* + * my_objs can only be freed when my_mutex is unlocked. + */ +int +my_obj_constructor(void *buf, void *ignored, int flags) +{ + my_obj_t *myobj = buf; + + (void) mutex_init(&my_obj->my_mutex, USYNC_THREAD, NULL); + + return (0); +} + +void +my_obj_destructor(void *buf, void *ignored) +{ + my_obj_t *myobj = buf; + + (void) mutex_destroy(&my_obj->my_mutex); +} + +umem_cache_t *my_obj_cache; + +\&... +my_obj_cache = umem_cache_create("my_obj", sizeof (my_obj_t), + 0, my_obj_constructor, my_obj_destructor, NULL, NULL, + NULL, 0); +\&... +my_obj_t *cur = umem_cache_alloc(my_obj_cache, UMEM_DEFAULT); +cur->my_data = 0; /* cannot assume anything about my_data */ +\&... +umem_cache_free(my_obj_cache, cur); +\&... +.fi +.in -2 + +.LP +\fBExample 3 \fRUse a more complex object with a mutex. +.sp +.in +2 +.nf +#define _REENTRANT +#include <assert.h> +#include <synch.h> +#include <umem.h> + +typedef struct my_obj { + mutex_t my_mutex; + cond_t my_cv; + struct bar *my_barlist; + unsigned my_refcount; +} my_obj_t; + +/* + * my_objs can only be freed when my_barlist == NULL, + * my_refcount == 0, there are no waiters on my_cv, and + * my_mutex is unlocked. + */ + +int +my_obj_constructor(void *buf, void *ignored, int flags) +{ + my_obj_t *myobj = buf; + + (void) mutex_init(&my_obj->my_mutex, USYNC_THREAD, NULL); + (void) cond_init(&my_obj->my_cv, USYNC_THREAD, NULL); + myobj->my_barlist = NULL; + myobj->my_refcount = 0; + + return (0); +} + +void +my_obj_destructor(void *buf, void *ignored) +{ + my_obj_t *myobj = buf; + + assert(myobj->my_refcount == 0); + assert(myobj->my_barlist == NULL); + (void) cond_destroy(&my_obj->my_cv); + (void) mutex_destroy(&my_obj->my_mutex); +} + +umem_cache_t *my_obj_cache; + +\&... +my_obj_cache = umem_cache_create("my_obj", sizeof (my_obj_t), + 0, my_obj_constructor, my_obj_destructor, NULL, NULL, + NULL, 0); +\&... +my_obj_t *cur = umem_cache_alloc(my_obj_cache, UMEM_DEFAULT); +\&... +/* use cur */ +\&... +umem_cache_free(my_obj_cache, cur); +\&... +.fi +.in -2 + +.LP +\fBExample 4 \fRUse objects with a subordinate buffer while reusing callbacks. +.sp +.in +2 +.nf +#include assert.h> +#include umem.h> + +typedef struct my_obj { + char *my_buffer; + size_t my_size; +} my_obj_t; + +/* + * my_size and the my_buffer pointer should never be changed + */ + +int +my_obj_constructor(void *buf, void *arg, int flags) +{ + size_t sz = (size_t)arg; + + my_obj_t *myobj = buf; + + if ((myobj->my_buffer = umem_alloc(sz, flags)) == NULL) + return (1); + + my_size = sz; + + return (0); +} + +void +my_obj_destructor(void *buf, void *arg) +{ + size_t sz = (size_t)arg; + + my_obj_t *myobj = buf; + + assert(sz == buf->my_size); + umem_free(myobj->my_buffer, sz); +} + +\&... +umem_cache_t *my_obj_4k_cache; +umem_cache_t *my_obj_8k_cache; +\&... +my_obj_cache_4k = umem_cache_create("my_obj_4k", sizeof (my_obj_t), + 0, my_obj_constructor, my_obj_destructor, NULL, + (void *)4096, NULL, 0); + +my_obj_cache_8k = umem_cache_create("my_obj_8k", sizeof (my_obj_t), + 0, my_obj_constructor, my_obj_destructor, NULL, + (void *)8192, NULL, 0); +\&... +my_obj_t *my_obj_4k = umem_cache_alloc(my_obj_4k_cache, + UMEM_DEFAULT); +my_obj_t *my_obj_8k = umem_cache_alloc(my_obj_8k_cache, + UMEM_DEFAULT); +/* no assumptions should be made about the contents +of the buffers */ +\&... +/* make sure to return them to the correct cache */ +umem_cache_free(my_obj_4k_cache, my_obj_4k); +umem_cache_free(my_obj_8k_cache, my_obj_8k); +\&... +.fi +.in -2 + +.sp +.LP +See the \fBEXAMPLES\fR section of \fBumem_alloc\fR(3MALLOC) for examples +involving the \fBUMEM_NOFAIL\fR flag. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityCommitted +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBsetcontext\fR(2), \fBatexit\fR(3C), \fBlibumem\fR(3LIB), \fBlongjmp\fR(3C), +\fBswapcontext\fR(3C), \fBthr_exit\fR(3C), \fBumem_alloc\fR(3MALLOC), +\fBumem_debug\fR(3MALLOC), \fBattributes\fR(5) +.sp +.LP +Bonwick, Jeff, "The Slab Allocator: An Object-Caching Kernel Memory Allocator", +Proceedings of the Summer 1994 Usenix Conference. +.sp +.LP +Bonwick, Jeff and Jonathan Adams, "Magazines and vmem: Extending the Slab +Allocator to Many CPUs and Arbitrary Resources", Proceedings of the Summer 2001 +Usenix Conference. +.SH WARNINGS +.sp +.LP +Any of the following can cause undefined results: +.RS +4 +.TP +.ie t \(bu +.el o +Destroying a cache that has outstanding allocated buffers. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +Using a cache after it has been destroyed. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +Calling \fBumem_cache_free()\fR on the same buffer multiple times. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +Passing a \fINULL\fR pointer to \fBumem_cache_free()\fR. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +Writing past the end of a buffer. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +Reading from or writing to a buffer after it has been freed. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +Performing \fBUMEM_NOFAIL\fR allocations from an \fBatexit\fR(3C) handler. +.RE +.sp +.LP +Per-cache callbacks can be called from a variety of contexts. The use of +functions that modify the active context, such as \fBsetcontext\fR(2), +\fBswapcontext\fR(3C), and \fBthr_exit\fR(3C), or functions that are unsafe for +use in multithreaded applications, such as \fBlongjmp\fR(3C) and +\fBsiglongjmp\fR(3C), result in undefined behavior. +.sp +.LP +A constructor callback that performs allocations must pass its \fIflags\fR +argument unchanged to \fBumem_alloc\fR(3MALLOC) and \fBumem_cache_alloc()\fR. +Any allocations made with a different flags argument results in undefined +behavior. The constructor must correctly handle the failure of any allocations +it makes. +.SH NOTES +.sp +.LP +Object caches make the following guarantees about objects: +.RS +4 +.TP +.ie t \(bu +.el o +If the cache has a constructor callback, it is applied to every object before +it is returned from \fBumem_cache_alloc()\fR for the first time. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +If the cache has a constructor callback, an object passed to +\fBumem_cache_free()\fR and later returned from \fBumem_cache_alloc()\fR is not +modified between the two events. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +If the cache has a destructor, it is applied to all objects before their +underlying storage is returned. +.RE +.sp +.LP +No other guarantees are made. In particular, even if there are buffers recently +freed to the cache, \fBumem_cache_alloc()\fR can fail. diff --git a/usr/src/man/man3malloc/umem_debug.3malloc b/usr/src/man/man3malloc/umem_debug.3malloc new file mode 100644 index 0000000000..52272331a1 --- /dev/null +++ b/usr/src/man/man3malloc/umem_debug.3malloc @@ -0,0 +1,232 @@ +'\" te +.\" Copyright (c) 2002, Sun Microsystems, Inc. All Rights Reserved. +.\" 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] +.TH umem_debug 3MALLOC "26 July 2002" "SunOS 5.11" "Memory Allocation Library Functions" +.SH NAME +umem_debug \- debugging features of the umem library +.SH SYNOPSIS +.LP +.nf +\fBcc\fR [ \fIflag\fR\&.\|.\|. ] \fIfile\fR\&.\|.\|. \fB-lumem\fR [ \fIlibrary\fR\&.\|.\|. ] +#include <\fBumem.h\fR> +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBlibumem\fR library provides debugging features that detect memory leaks, +buffer overruns, multiple frees, use of uninitialized data, use of freed data, +and many other common programming errors. The activation of the run-time +debugging features is controlled by environment variables. +.sp +.LP +When the library detects an error, it writes a description of the error to an +internal buffer that is readable with the \fB::umem_status\fR \fBmdb\fR(1) +\fIdcmd\fR and then calls \fBabort\fR(3C). +.SH ENVIRONMENT VARIABLES +.sp +.ne 2 +.mk +.na +\fB\fBUMEM_DEBUG\fR\fR +.ad +.RS 16n +.rt +This variable contains a list of comma-separated options. Unrecognized options +are ignored. Possible options include: +.sp +.ne 2 +.mk +.na +\fB\fBaudit\fR[=\fIframes\fR]\fR +.ad +.RS 20n +.rt +This option enables the recording of auditing information, including thread ID, +high-resolution time stamp, and stack trace for the last action (allocation or +free) on every allocation. If transaction logging (see \fBUMEM_LOGGING\fR) is +enabled, this auditing information is also logged. +.sp +The \fIframes\fR parameter sets the number of stack frames recorded in the +auditing structure. The upper bound for frames is implementation-defined. If a +larger value is requested, the upper bound is used instead. +.sp +If \fIframes\fR is not specified or is not an integer, the default value of 15 +is used. +.sp +This option also enables the \fBguards\fR option. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBcontents\fR[=\fIcount\fR]\fR +.ad +.RS 20n +.rt +If auditing and contents logging (see \fBUMEM_LOGGING\fR) are enabled, the +first \fIcount\fR bytes of each buffer are logged when they are freed. If a +buffer is shorter than \fIcount\fR bytes, it is logged in its entirety. +.sp +If \fIcount\fR is not specified or is not an integer, the default value of 256 +is used. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBdefault\fR\fR +.ad +.RS 20n +.rt +This option is equivalent to \fBaudit\fR,\fBcontents\fR,\fBguards\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBguards\fR\fR +.ad +.RS 20n +.rt +This option enables filling allocated and freed buffers with special patterns +to help detect the use of uninitialized data and previously freed buffers. It +also enables an 8-byte redzone after each buffer that contains +\fB0xfeedfacefeedfaceULL\fR. +.sp +When an object is freed, it is filled with \fB0xdeadbeef\fR. When an object is +allocated, the \fB0xdeadbeef\fR pattern is verified and replaced with +\fB0xbaddcafe\fR. The redzone is checked every time a buffer is allocated or +freed. +.sp +For caches with either constructors or destructors, or both, +\fBumem_cache_alloc\fR(3MALLOC) and \fBumem_cache_free\fR(3MALLOC) apply the +cache's constructor and destructor, respectively, instead of caching +constructed objects. The presence of \fBassert\fR(3C)s in the destructor +verifying that the buffer is in the constructed state can be used to detect any +objects returned in an improper state. See \fBumem_cache_create\fR(3MALLOC) +for details. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBverbose\fR\fR +.ad +.RS 20n +.rt +The library writes error descriptions to standard error before aborting. These +messages are not localized. +.RE + +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBUMEM_LOGGING\fR\fR +.ad +.RS 16n +.rt +To be enabled, this variable should be set to a comma-separated list of +in-memory logs. The logs available are: +.sp +.ne 2 +.mk +.na +\fB\fBtransaction\fR[=\fIsize\fR]\fR +.ad +.RS 22n +.rt +If the \fBaudit\fR debugging option is set (see \fBUMEM_DEBUG\fR), the audit +structures from previous transactions are entered into this log. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBcontents\fR[=\fIsize\fR]\fR +.ad +.RS 22n +.rt +If the \fBaudit\fR debugging option is set, the contents of objects are +recorded in this log as they are freed. +.sp +If the "contents" debugging option was not set, 256 bytes of each freed buffer +are saved. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBfail\fR[=\fIsize\fR]\fR +.ad +.RS 22n +.rt +Records are entered into this log for every failed allocation. +.RE + +For any of these options, if \fIsize\fR is not specified, the default value of +64k is used. The \fIsize\fR parameter must be an integer that can be qualified +with K, M, G, or T to specify kilobytes, megabytes, gigabytes, or terabytes, +respectively. +.sp +Logs that are not listed or that have either a size of 0 or an invalid size are +disabled. +.sp +The log is disabled if during initialization the requested amount of storage +cannot be allocated. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityUnstable +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBmdb\fR(1), \fBabort\fR(3C), \fBsignal\fR(3C), +\fBumem_cache_create\fR(3MALLOC), \fBattributes\fR(5) +.sp +.LP +\fISolaris Modular Debugger Guide\fR +.SH WARNINGS +.sp +.LP +When \fBlibumem\fR aborts the process using \fBabort\fR(3C), any existing +signal handler for \fBSIGABRT\fR is called. If the signal handler performs +allocations, undefined behavior can result. +.SH NOTES +.sp +.LP +Some of the debugging features work only for allocations smaller than 16 +kilobytes in size. Allocations larger than 16 kilobytes could have reduced +support. +.sp +.LP +Activating any of the library's debugging features could significantly increase +the library's memory footprint and decrease its performance. diff --git a/usr/src/man/man3malloc/watchmalloc.3malloc b/usr/src/man/man3malloc/watchmalloc.3malloc new file mode 100644 index 0000000000..364c359952 --- /dev/null +++ b/usr/src/man/man3malloc/watchmalloc.3malloc @@ -0,0 +1,234 @@ +'\" te +.\" Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved. +.\" 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] +.TH watchmalloc 3MALLOC "10 Jan 2007" "SunOS 5.11" "Memory Allocation Library Functions" +.SH NAME +watchmalloc \- debugging memory allocator +.SH SYNOPSIS +.LP +.nf +#include <stdlib.h> + +\fBvoid *\fR\fBmalloc\fR(\fBsize_t\fR \fIsize\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBfree\fR(\fBvoid *\fR\fIptr\fR); +.fi + +.LP +.nf +\fBvoid *\fR\fBrealloc\fR(\fBvoid *\fR\fIptr\fR, \fBsize_t\fR \fIsize\fR); +.fi + +.LP +.nf +\fBvoid *\fR\fBmemalign\fR(\fBsize_t\fR \fIalignment\fR, \fBsize_t\fR \fIsize\fR); +.fi + +.LP +.nf +\fBvoid *\fR\fBvalloc\fR(\fBsize_t\fR \fIsize\fR); +.fi + +.LP +.nf +\fBvoid *\fR\fBcalloc\fR(\fBsize_t\fR \fInelem\fR, \fBsize_t\fR \fIelsize\fR); +.fi + +.LP +.nf +#include <malloc.h> + +\fBint\fR \fBmallopt\fR(\fBint\fR \fIcmd\fR, \fBint\fR \fIvalue\fR); +.fi + +.LP +.nf +\fBstruct mallinfo\fR \fBmallinfo\fR(\fBvoid\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The collection of \fBmalloc()\fR functions in this shared object are an +optional replacement for the standard versions of the same functions in the +system C library. See \fBmalloc\fR(3C). They provide a more strict interface +than the standard versions and enable enforcement of the interface through the +watchpoint facility of \fB/proc\fR. See \fBproc\fR(4). +.sp +.LP +Any dynamically linked application can be run with these functions in place of +the standard functions if the following string is present in the environment +(see \fBld.so.1\fR(1)): +.sp +.in +2 +.nf + LD_PRELOAD=watchmalloc.so.1 +.fi +.in -2 + +.sp +.LP +The individual function interfaces are identical to the standard ones as +described in \fBmalloc\fR(3C). However, laxities provided in the standard +versions are not permitted when the watchpoint facility is enabled (see +\fBWATCHPOINTS\fR below): +.RS +4 +.TP +.ie t \(bu +.el o +Memory may not be freed more than once. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +A pointer to freed memory may not be used in a call to \fBrealloc()\fR. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +A call to \fBmalloc()\fR immediately following a call to \fBfree()\fR will not +return the same space. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +Any reference to memory that has been freed yields undefined results. +.RE +.sp +.LP +To enforce these restrictions partially, without great loss in speed as +compared to the watchpoint facility described below, a freed block of memory is +overwritten with the pattern \fB0xdeadbeef\fR before returning from +\fBfree()\fR. The \fBmalloc()\fR function returns with the allocated memory +filled with the pattern \fB0xbaddcafe\fR as a precaution against applications +incorrectly expecting to receive back unmodified memory from the last +\fBfree()\fR. The \fBcalloc()\fR function always returns with the memory +zero-filled. +.sp +.LP +Entry points for \fBmallopt()\fR and \fBmallinfo()\fR are provided as empty +routines, and are present only because some \fBmalloc()\fR implementations +provide them. +.SH WATCHPOINTS +.sp +.LP +The watchpoint facility of \fB/proc\fR can be applied by a process to itself. +The functions in \fBwatchmalloc.so.1\fR use this feature if the following +string is present in the environment: +.sp +.LP +MALLOC_DEBUG=WATCH +.sp +.LP +This causes every block of freed memory to be covered with \fBWA_WRITE\fR +watched areas. If the application attempts to write any part of freed memory, +it will trigger a watchpoint trap, resulting in a \fBSIGTRAP\fR signal, which +normally produces an application core dump. +.sp +.LP +A header is maintained before each block of allocated memory. Each header is +covered with a watched area, thereby providing a red zone before and after each +block of allocated memory (the header for the subsequent memory block serves as +the trailing red zone for its preceding memory block). Writing just before or +just after a memory block returned by \fBmalloc()\fR will trigger a watchpoint +trap. +.sp +.LP +Watchpoints incur a large performance penalty. Requesting +\fBMALLOC_DEBUG=WATCH\fR can cause the application to run 10 to 100 times +slower, depending on the use made of allocated memory. +.sp +.LP +Further options are enabled by specifying a comma-separated string of options: +.sp +.LP +MALLOC_DEBUG=WATCH,RW,STOP +.sp +.ne 2 +.mk +.na +\fB\fBWATCH\fR\fR +.ad +.RS 9n +.rt +Enables \fBWA_WRITE\fR watched areas as described above. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBRW\fR\fR +.ad +.RS 9n +.rt +Enables both \fBWA_READ\fR and \fBWA_WRITE\fR watched areas. An attempt either +to read or write freed memory or the red zones will trigger a watchpoint trap. +This incurs even more overhead and can cause the application to run up to 1000 +times slower. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBSTOP\fR\fR +.ad +.RS 9n +.rt +The process will stop showing a \fBFLTWATCH\fR machine fault if it triggers a +watchpoint trap, rather than dumping core with a \fBSIGTRAP\fR signal. This +allows a debugger to be attached to the live process at the point where it +underwent the watchpoint trap. Also, the various \fB/proc\fR tools described in +\fBproc\fR(1) can be used to examine the stopped process. +.RE + +.sp +.LP +One of \fBWATCH\fR or \fBRW\fR must be specified, else the watchpoint facility +is not engaged. \fBRW\fR overrides \fBWATCH\fR. Unrecognized options are +silently ignored. +.SH LIMITATIONS +.sp +.LP +Sizes of memory blocks allocated by \fBmalloc()\fR are rounded up to the +worst-case alignment size, 8 bytes for 32-bit processes and 16 bytes for 64-bit +processes. Accessing the extra space allocated for a memory block is +technically a memory violation but is in fact innocuous. Such accesses are not +detected by the watchpoint facility of \fBwatchmalloc\fR. +.sp +.LP +Interposition of \fBwatchmalloc.so.1\fR fails innocuously if the target +application is statically linked with respect to its \fBmalloc()\fR functions. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBproc\fR(1), \fBbsdmalloc\fR(3MALLOC), \fBcalloc\fR(3C), \fBfree\fR(3C), +\fBmalloc\fR(3C), \fBmalloc\fR(3MALLOC), \fBmapmalloc\fR(3MALLOC), +\fBmemalign\fR(3C), \fBrealloc\fR(3C), \fBvalloc\fR(3C), +\fBlibmapmalloc\fR(3LIB), \fBproc\fR(4), \fBattributes\fR(5) |