MALLOC_CV(3) MALLOC_CV(3)
malloc, free, realloc, calloc, memalign, valloc, cvmalloc_error -
WorkShop memory allocation library
#include <stdlib.h>
void *malloc (size_t size);
void free (void *ptr);
void *realloc (void *ptr, size_t size);
void *calloc (size_t nelem, size_t elsize);
void *memalign (size_t alignment, size_t size);
void *valloc (size_t size);
void cvmalloc_error (char *message);
The WorkShop Performance Tools contain a malloc library, -lmalloc_cv,
which provides tracing and error detection around calls to the various
malloc routines.
The library provides an intercept layer for calls to malloc, free,
realloc, memalign, and valloc; the intercept allows tracing of all calls
with the WorkShop performance tools.
Calls to malloc, free, and realloc are passed through to whatever memory
allocation library the program is linked with. Calls to calloc are
actually not intercepted, but rely on the underlying calloc to call
malloc to get the space allocated. Calls to memalign are implemented by
allocating a block large enough to hold the aligned area asked for by the
user, as well as a guard area that holds a flag indicating that the user
block was obtained through memalign, and the address of the larger block.
Calls to valloc are translated into a call to getpagesize, followed by a
memalign call.
The last function, cvmalloc_error is called whenever any error is
detected; a debugger trap may be placed at exit from that routine to
interactively examine malloc errors.
The library provides for tracing of all calls to any of the entry points
listed above, as well as any of the errors listed below. The trace is
normally captured using a WorkShop performance experiment. It may be
written in ASCII to stderr by enabling the environment variable
MALLOC_TRACING, although this typically produces a great deal of output.
Page 1
MALLOC_CV(3) MALLOC_CV(3)
The library will detect some errors under all conditions, and others if
MALLOC_FASTCHK error detection is enabled. All errors pass through the
routine cvmalloc_error and a trap can be placed at the exit from that
routine to catch the problem. Errors are also traced.
The errors that are always detected are:
malloc call failing (returning NULL).
realloc call failing (returning NULL).
realloc call with an address outside the range of heap addresses
returned by malloc or memalign.
memalign call with an improper alignment.
free call with an address that is improperly aligned.
free call with an address outside the range of heap addresses
returned by malloc or memalign.
If MALLOC_FASTCHK is enabled, the library will also detect:
free or realloc calls where the words prior to the user block have
been corrupted.
free or realloc calls where the words following the user block have
been corrupted.
free or realloc calls where the address is that of a block that has
already been freed. This error may not always be detected if the
area around the block is reallocated after it was first freed.
The behavior of the library is governed by various environment variables:
MALLOC_VERBOSE n [Toc] [Back]
(where n is an integer) controls printing of messages from the
library. If n = 0, messages are printed to stderr ony when an error
occurs. If n = 1 (the default), a messages is printed during
initialization, so that the user can tell that the library was
properly included in the application. If n = 2 or greater, detailed
information about all traced events, including the callstack at the
time the error was detected, is printed. This option is not
normally used by the end user, as it can produce a huge vloume of
output.
MALLOC_TRACING [Toc] [Back]
enables tracing of all calls through the library. Tracing is
normally done in the course of a performance experiment; the
variable need not be set in such cases, as the running of the
experiment will automatically enable it. If the option is enabled
when the program is run independently, and MALLOC_VERBOSE is set to
2 or greater, the trace events and program call stacks will be
written to stderr.
MALLOC_FASTCHK [Toc] [Back]
enables corruption detection for library calls. Corruption
detection is done by allocating a space larger than the requested
area, and putting specific patterns in front of and behind the area
returned to the caller. When free is called, the patterns are
Page 2
MALLOC_CV(3) MALLOC_CV(3)
checked, and if the area was overwritten, an error message is
printed using an internal call to the routine cvmalloc_error. Under
the debugger, a trap may be set at exit from this routine to catch
the program at the error.
MALLOC_FULLWARN [Toc] [Back]
enables detection of some calls that are not strictly errors, but
represent sloppy programming, including free(NULL), malloc(0), and
realloc(ptr,0).
MALLOC_MAXMALLOC n [Toc] [Back]
(where n is an integer, in any base) sets a maximum size for any
malloc or realloc or memalign allocation. Any request exceeding
that size will be flagged as an error, and return a NULL pointer.
MALLOC_NO_REUSE [Toc] [Back]
specifies that no area that has been freed will be reused. With
this option enabled, no actual free calls are really made, and the
process space and swap requirements can grow quite large. If
MALLOC_FASTCHK is not enabled, any space that is freed by a realloc
may or may not get reused; if MALLOC_FASTCHK is enabled, such space
will not be reused.
MALLOC_CLEAR_FREE [Toc] [Back]
will clear the data upon any free call. It will only work if
MALLOC_FASTCHK is also enabled.
MALLOC_CLEAR_FREE_PATTERN <pattern>
specifies a pattern to clear the data if MALLOC_CLEAR_FREE is
enabled. The default pattern is 0xcafebeef for the 32-bit version,
and 0xcafebeefcafebeef for the 64-bit versions. Only full words
(double words for 64-bits) are cleared to the pattern.
MALLOC_CLEAR_MALLOC [Toc] [Back]
will clear the memory area upon each allocation. It also requires
MALLOC_FASTCHK be enabled.
MALLOC_CLEAR_MALLOC_PATTERN <pattern>
specifies a pattern to clear the data if MALLOC_CLEAR_MALLOC is
enabled. The default pattern is 0xfacebeef for the 32-bit version,
and 0xfacebeeffacebeef for the 64-bit versions. Only full words
(double words for 64-bits) are cleared to the pattern.
malloc(3C), malloc(3X), cvspeed(1), cvperf(1).
As ouput from the library routines.
Page 3
MALLOC(3F) MALLOC(3F)
malloc, free - main memory allocator
FORTRAN SYNOPSIS
pointer (iptr, arr)
dimension arr(1)
integer nbytes
iptr = malloc(nbytes)
call free(iptr)
malloc and free provide a simple general-purpose memory allocation
package. malloc returns a pointer to a block of at least nbytes bytes
suitably aligned for any use.
arr can be an array of any type. After the call to malloc the array arr
can be used as if it has been declared as an array with nbytes in length.
All references to this array will be deferenced using the value assigned
to iptr in the malloc call to refer to the space allocated by malloc.
The argument to free is a pointer to a block previously allocated by
malloc; after free is performed this space is made available for further
allocation, but its contents are left undisturbed.
Undefined results will occur if the space assigned by malloc is overrun
or if some random number is handed to free.
malloc allocates the first big enough contiguous reach of free space
found in a circular search from the last block allocated or freed,
coalescing adjacent free blocks as it searches. It calls sbrk [see
brk(2)] to get more memory from the system when there is no suitable
space already free.
malloc, returns a NULL pointer if there is no available memory or if the
arena has been detectably corrupted by storing outside the bounds of a
block. When this happens the block pointed to by iptr may be destroyed.
Search time increases when many objects have been allocated; that is, if
a program allocates but never frees, then each successive allocation
takes longer.
Note that the system may be configured with virtual swap space. This
allows processes to allocate more virtual memory than is actually
available, allowing the use of sparse addressing, successful forks and
subsequent execs by programs larger than 1/2 the available virtual
memory, and so forth. Thus programs using malloc may get a successful
return, but later be sent the SIGKILL signal if virtual memory was
overcommitted, and processes attempt to actually use all of the
Page 1
MALLOC(3F) MALLOC(3F)
overcommitted memory. If the system has no virtual swap space
configured, then processes are limited to using no more virtual memory
than the sum of physical memory and swap space. See the section on
"Logical Swap Space" in the swap(1M) man page for more information.
Page 2
MALLOC(3C) MALLOC(3C)
malloc, free, realloc, calloc, memalign, valloc - main memory allocator
#include <stdlib.h>
void *malloc (size_t size);
void free (void *ptr);
void *realloc (void *ptr, size_t size);
void *calloc (size_t nelem, size_t elsize);
void *memalign (size_t alignment, size_t size);
void *valloc (size_t size);
malloc and free provide a simple general-purpose memory allocation
package. malloc returns a pointer to a block of at least size bytes
suitably aligned for any use.
The argument to free is a pointer to a block previously allocated by
malloc; after free is performed this space is made available for further
allocation, but its contents are left undisturbed.
Undefined results will occur if the space allocated by malloc is overrun
or if some random value is passed as the argument to free.
malloc allocates the first big enough contiguous reach of free space
found in a circular search from the last block allocated or freed,
coalescing adjacent free blocks as it searches. It calls sbrk [see
brk(2)] to get more memory from the system when there is no suitable
space already free.
realloc changes the size of the block pointed to by ptr to size 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 no free block of
size bytes is available in the storage arena, then realloc will ask
malloc to enlarge the arena by size bytes and will then move the data to
the new space. If ptr is NULL, realloc behaves like malloc(size). If
size is zero, the storage associated with ptr is freed and realloc
returns the same result as does malloc(0).
calloc allocates space for an array of nelem elements of size elsize.
The space is initialized to zeros.
memalign allocates size bytes on a specified alignment boundary and
returns a pointer to the allocated block. The value of the returned
address is guaranteed to be a multiple of alignment. Note that the value
of alignment must be a power of two and must be greater than or equal to
Page 1
MALLOC(3C) MALLOC(3C)
the size of a word, or, for 64 bit objects, the size of a doubleword.
valloc(size) is equivalent to memalign(sysconf(_SC_PAGESIZE),size). For
more information see sysconf(3c).
Each of the allocation routines returns a pointer to space suitably
aligned (after possible pointer coercion) for storage of any type of
object.
brk(2), sysconf(3c), malloc(3X)
malloc, realloc, calloc, memalign, and valloc return a NULL pointer if
there is no available memory or if the arena has been detectably
corrupted by storing outside the bounds of a block. When this happens
the block pointed to by ptr may be destroyed.
How an application manages its heap can greatly affect the performance of
these routines. For most applications, this set will perform well. For
some applications, the more flexible malloc(3X) package might be more
appropriate.
A SEGV or Bus Error inside the malloc routine is almost certainly caused
by a previous memory overwrite by the user. This is a delayed error which
is caused by a previous overwrite of unallocated memory and is not a bug
in malloc itself.
When called with size of zero, malloc returns a valid pointer to a block
of zero bytes. Storage into a block of length zero will corrupt the
malloc arena and may have serious consequences.
Products, libraries, or commands that provide their own malloc package
must provide all of the entry points listed above, or the normal libc
malloc entry point for the unimplemented routine(s) may be called
instead, leading to corrupted heaps, since it is unlikely that the
internal details of the heap management will be the same. If the malloc
package is also intended to replace malloc(3X), it must also provide the
additional routines listed there.
Page 2
MALLOC(3X) MALLOC(3X)
malloc, free, realloc, calloc, mallopt, mallinfo, mallocblksize,
recalloc, memalign - fast main memory allocator
#include <sys/types.h>
#include <malloc.h>
void *malloc (size_t size);
void free (void *ptr);
void *realloc (void *ptr, size_t size);
void *calloc (size_t nelem, size_t elsize);
int mallopt (int cmd, int value);
struct mallinfo mallinfo(void);
size_t mallocblksize (void *ptr);
void *recalloc (void *ptr, size_t nelem, size_t elsize);
void *memalign (size_t align, size_t size);
malloc and free provide a simple general-purpose memory allocation
package, which is more flexible than the malloc(3c) package and,
depending on an application's usage, may provide better performance. It
is found in the library ``libmalloc.so'', and is loaded if the option
``-lmalloc'' is used with cc(1) or ld(1).
malloc returns a pointer to a block of at least size bytes suitably
aligned for any use.
The argument to free is a pointer to a block previously allocated by
malloc; after free is performed this space is made available for further
allocation, and its contents are destroyed (see mallopt below for a way
to change this behavior).
Undefined results will occur if the space assigned by malloc is overrun
or if some random number is handed to free. It is always permitted to
pass NULL to free.
realloc changes the size of the block pointed to by ptr to size 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. In the special case
of a null ptr, realloc degenerates to malloc. A zero size causes the
passed block to be freed.
Page 1
MALLOC(3X) MALLOC(3X)
calloc allocates space for an array of nelem elements of size elsize.
The space is initialized to zeros.
recalloc combines realloc and calloc. If the size of the block
increases, any new bytes are initialized to zero. Note that for this to
work properly, all allocations of a given pointer must go through
recalloc. If the original pointer was allocated with either malloc,
calloc, or realloc some new bytes may not be set properly to zero.
memalign allocates size 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 align. Note: the value
of align must be a multiple of a word (for 64 bit objects, a doubleword,)
and must be greater than or equal to the size of a word, or, for 64 bit
objects, the size of a doubleword.
mallocblksize returns the actual size of the block pointed to by ptr.
The returned size may be greater than the original requested size due to
padding and alignment.
mallopt provides for control over the allocation algorithm. The
available values for cmd are:
M_MXFAST Set maxfast to value. The algorithm allocates all blocks at or
below the size of maxfast in large groups and then doles them
out very quickly. The default value for maxfast is 28.
M_NLBLKS Set numlblks to value. The above mentioned ``large groups''
each contain numlblks blocks. numlblks must be greater than 0.
The default value for numlblks is 100.
M_GRAIN Set grain to value. Requests less than or equal to maxfast will
have the size of a pointer added to them and be rounded up to
the next multiple of grain. value will be rounded up to a
multiple of the alignment size (8 bytes for 32 bit programs, 16
bytes for 64 bit programs) when grain is set. grain must be
greater than 0. The default value of grain is 8 for 32 bit
programs, 16 for 64 bit programs.
M_KEEP Preserve data in a freed block until the next malloc, realloc,
or calloc. This option is provided only for compatibility with
older versions of malloc and is not recommended.
M_DEBUG Turns debug checking on if value is not equal to 0, otherwise
turns debug checking off. When debugging is on, each call to
malloc and free causes the entire malloc arena to be scanned and
checked for consistency. This option may be invoked at any
time. Note that when debug checking is on, the performance of
malloc is reduced considerably. If corruption is detected in
the arena, the checking code calls abort(3C). This usually
results in the calling process exiting and leaving a core file
in its current directory.
Page 2
MALLOC(3X) MALLOC(3X)
M_BLKSZ When malloc requires additional space, it uses sbrk(2) to
allocate enough memory for the current malloc request rounded up
to a minimum size (default is 8K). The new size is set to value
after it has been rounded up to the current block alignment.
value must be at least 512 bytes. If a lot of space is to be
allocated, setting the size larger can cut down on the system
overhead. This option may be invoked at any time.
M_MXCHK By default, malloc trades off time versus space - if anywhere in
the arena there is a block of the appropriate size, malloc will
find and return it. If the arena has become fragmented due to
many mallocs and frees, it is possible that malloc will have to
search through many blocks to find one of the appropriate size.
If the arena is severely fragmented, the average malloc time can
be on the order of tens of milliseconds (as opposed to a normal
average of tens of microseconds). This option allows the user
to place a limit on the number of blocks that malloc will search
through before allocating a new block of space from the system.
Small values (less than 50) can cause much more memory to be
allocated. Values around 100 (the default) cause very uniform
response time, with a small space penalty. This option may be
invoked at any time.
M_FREEHD When value is not zero, free, recalloc, and realloc will place
any freed memory in the front of the free list(s) instead of at
the end (which is the default). Some applications will benefit
in processing speed and space compaction by having freed memory
placed at the beginning of the free list(s).
M_CLRONFREE
With this option, all blocks that are freed are set to value.
This option may be set at any time, but there is no way to turn
it off. That part of the beginning of a freed block which is
used for internal pointers will of course not be set to value.
These values are defined in the <malloc.h> header file.
mallopt may be called repeatedly, but, for most commands, may not be
called after the first small block is allocated.
mallinfo provides instrumentation describing space usage. It returns the
structure (defined in <malloc.h>):
struct mallinfo {
int arena; /* total space in arena */
int ordblks; /* number of ordinary blocks */
int smblks; /* number of small blocks */
int hblkhd; /* space in holding block headers */
int hblks; /* number of holding blocks */
int usmblks; /* space in small blocks in use */
int fsmblks; /* space in free small blocks */
int uordblks; /* space in ordinary blocks in use */
Page 3
MALLOC(3X) MALLOC(3X)
int fordblks; /* space in free ordinary blocks */
int keepcost; /* space penalty if keep option */
/* is used */
}
For example, an application wishing to determine how many bytes it has
currently malloc'd should add the usmblks and uordblks fields. That
total may also include some space that malloc allocates internally for
its own use, and that extra space cannot be free'd.
Each of the allocation routines returns a pointer to space suitably
aligned (after possible pointer coercion) for storage of any type of
object.
brk(2), malloc(3C), memalign(3C), amalloc(3P), valloc(3C).
malloc, recalloc, memalign, realloc and calloc return a NULL pointer if
there is not enough available memory or size is 0. memalign will also
return NULL if align is 0 or not a 4 byte multiple (8 byte multiple for
64-bit programs). When realloc or recalloc returns NULL, the block
pointed to by ptr is left intact. If mallopt is called after any
allocation (for most cmd arguments) or if cmd or value are invalid, nonzero
is returned. Otherwise, it returns zero.
Note that unlike malloc(3C), this package does not preserve the contents
of a block when it is freed, unless the M_KEEP option of mallopt is used.
Undocumented features of malloc(3C) have not been duplicated.
Products, libraries, or commands that provide their own malloc package
must provide all of the entry points listed above, or the normal
libmalloc or libc malloc entry point for the unimplmented routine(s) may
be called instead, leading to corrupted heaps, as it is unlikely that the
internal details of the heap management will be the same. If the package
is a replacement for the libc set, but not the libmalloc set, it is not
necessary to supply the mallopt, mallinfo, mallocblksize, or recalloc
routines.
PPPPaaaaggggeeee 4444 [ Back ]
|
