aboutsummaryrefslogtreecommitdiff
path: root/manual/memory.texi
diff options
context:
space:
mode:
authorUlrich Drepper <drepper@redhat.com>1997-04-08 23:42:08 +0000
committerUlrich Drepper <drepper@redhat.com>1997-04-08 23:42:08 +0000
commitc131718ccc1db101df54fb04f34f5611c3678450 (patch)
tree14fd2f6b9e1cc7f3cfbf03da2f95bb56c8be94af /manual/memory.texi
parent26dee9c49cbbec8826db4c29e99fb50d9392a047 (diff)
downloadglibc-c131718ccc1db101df54fb04f34f5611c3678450.zip
glibc-c131718ccc1db101df54fb04f34f5611c3678450.tar.gz
glibc-c131718ccc1db101df54fb04f34f5611c3678450.tar.bz2
1997-04-09 01:24 Ulrich Drepper <drepper@cygnus.com> * rellns-sh: Rewrite to work also in presence of symlinks. * arpg/argp-fmtstream.c: Add casts to prevent warnings. * argp/argp-fmtstream.h: Likewise. * argp/argp-help.c: Likewise. * elf/dl-minimal.c: Add definition of calloc. * elf/version.c: Add casts to prevent warnings. (_dl_check_map_versions): Use calloc instead of malloc+memset. * locale/setlocale.c (_nl_current): Add element with index LC_ALL. Reported by Greg McGary <gkm@eng.ascend.com>. * manual/libc.texinfo: Update malloc documentation for new malloc. * manual/memory.texi: Likewise. Patch by Wolfram Gloger <wmglo@dent.med.uni-muenchen.de>. * math/libm-test.c (check_long): New function. (check_longlong): New function. (rinttol_test): New function. (rinttoll_test): New function. * nis/nss_compat/compat-grp.c (in_blacklist): Improve a bit. * nis/nss_compat/compat-pwd.c: Likewise. * nis/nss_compat/compat-spwd.c: Likewise. * stdlib/erand48_r.c (erand48_r): Build double value using ieee754_double union and use random bits in different order to increase effect of seed. Reported by David Mosberger-Tang <davidm@AZStarNet.com>. * sunrpc/svc_auth.c: Moved to ... * sysdeps/generic/svc_auth.c: ...here. * time/time.h: Pretty print. 1997-04-08 07:19 H.J. Lu <hjl@gnu.ai.mit.edu> * libio/genops.c (_IO_flush_all_linebuffered): don't flush on a read-only stream. 1997-04-09 01:19 Ulrich Drepper <drepper@cygnus.com> * malloc/malloc.c (mALLOC_STATs) [MALLOC_DEBUG>1]: Put declaration in correct place. Patch by Marcus G. Daniels <marcus@cathcart.sysc.pdx.edu>. 1997-04-07 15:34 Ulrich Drepper <drepper@cygnus.com> * stdio-common/Makefile (tests): Add tst-ferror. * stdio-common/tst-ferror.c: New file. Some tests for error indicator of streams. * stdio-common/tst-ferror.input: New file. * isomac.c: Let tests not fail because the compiler defines itself symbols which violate the name space rules. gcc defines symbols for the architecture which are not protected by an underscore character. * math/Makefile (libm-support): Add s_rinttol and s_rinttoll. (libm-calls): Add s_clog. * sysdeps/libm-ieee754/s_clog.c: New file. Implementation of logarithm of complex value. * sysdeps/libm-ieee754/s_clogf.c: New file. * sysdeps/libm-ieee754/s_clogl.c: New file. * math/libm-test.c (clog_test): Compile this function. Fix a few typos. (main): Call clog_test. * sysdeps/libm-ieee754/s_rinttol.c: New file. Round long double value to long int. * sysdeps/libm-i387/s_rinttol.S: New file. * sysdeps/libm-ieee754/s_rinttoll.c: new file. Round long double value to long long int. * sysdeps/libm-i387/s_rinttoll.S: New file. * sysdeps/libm-ieee754/s_rintl.c: Many corrections. The previous version was full of errors. * math/math.h (rinttol): Argument is of type `long double' not `double'. (rinttoll): Likewise. (roundtol): Likewise. (roundtoll): Likewise. 1997-04-06 11:32 H.J. Lu <hjl@gnu.ai.mit.edu> * posix/getopt.c (_getopt_initialize): Preserve optind. (_getopt_internal): Set optind to 1 if optind == 0 before calling _getopt_initialize (). 1997-04-05 16:45 Thorsten Kukuk <kukuk@vt.uni-paderborn.de> * nis/rpcsvc/nislib.h: Change const nis_name to new type const_nis_name. * nis/nis_intern.c: Likewise. * nis/nis_intern.h: Likewise. * nis/nis_server.c: Likewise. * nis/nis_subr.c: Likewise. * nis/nis_table.c: Likewise. * nis/nis_names.c: Likewise. Fill out ns_request structure in nis_add(). * nis/nss_compat/compat-pwd.c: Use reentrant netgroup functions. * nis/nss_compat/compat-spwd.c: Likewise. 1997-03-27 07:37 H.J. Lu <hjl@gnu.ai.mit.edu> * libio/fileops.c (_IO_file_overflow): Set error when try to write on a read-only stream. * sysdeps/gnu/utmpbits.h (ut_xtime): New symbol. (ut_time): Define it only if _NO_UT_TIME is not defined. 1997-04-06 00:42 Ulrich Drepper <drepper@cygnus.com> * misc/tst-tsearch.c: Include <string.h>. Define _GNU_SOURCE only if not already defined. 1997-04-05 16:14 Ulrich Drepper <drepper@cygnus.com> * sysdeps/unix/sysv/linux/netatalk/at.h: Include <sys/socket.h> to get definition of sa_family_t for <linux/atalk.h>. Reported by a sun <asun@zoology.washington.edu>. * malloc/malloc.c (cALLOc): Little optimization.
Diffstat (limited to 'manual/memory.texi')
-rw-r--r--manual/memory.texi175
1 files changed, 133 insertions, 42 deletions
diff --git a/manual/memory.texi b/manual/memory.texi
index 9ebe31e..16dc9aa 100644
--- a/manual/memory.texi
+++ b/manual/memory.texi
@@ -38,7 +38,6 @@ will be freed automatically. @xref{Variable Size Automatic}.
calling function returns.
* Relocating Allocator:: Waste less memory, if you can tolerate
automatic relocation of the blocks you get.
-* Memory Warnings:: Getting warnings when memory is nearly full.
@end menu
@node Memory Concepts
@@ -140,6 +139,8 @@ any time (or never).
these functions.
* Aligned Memory Blocks:: Allocating specially aligned memory:
@code{memalign} and @code{valloc}.
+* Malloc Tunable Parameters:: Use @code{mallopt} to adjust allocation
+ parameters.
* Heap Consistency Checking:: Automatic checking for errors.
* Hooks for Malloc:: You can use these hooks for debugging
programs that use @code{malloc}.
@@ -238,10 +239,10 @@ savestring (const char *ptr, size_t len)
The block that @code{malloc} gives you is guaranteed to be aligned so
that it can hold any type of data. In the GNU system, the address is
-always a multiple of eight; if the size of block is 16 or more, then the
-address is always a multiple of 16. Only rarely is any higher boundary
-(such as a page boundary) necessary; for those cases, use
-@code{memalign} or @code{valloc} (@pxref{Aligned Memory Blocks}).
+always a multiple of eight on most systems, and a multiple of 16 on
+64-bit systems. Only rarely is any higher boundary (such as a page
+boundary) necessary; for those cases, use @code{memalign} or
+@code{valloc} (@pxref{Aligned Memory Blocks}).
Note that the memory located after the end of the block is likely to be
in use for something else; perhaps a block already allocated by another
@@ -368,9 +369,11 @@ xrealloc (void *ptr, size_t size)
@end smallexample
You can also use @code{realloc} to make a block smaller. The reason you
-would do this is to avoid tying up a lot of memory space when only a little
-is needed. Making a block smaller sometimes necessitates copying it, so it
-can fail if no other space is available.
+is needed.
+@comment The following is no longer true with the new malloc.
+@comment But it seems wise to keep the warning for other implementations.
+In several allocation implementations, making a block smaller sometimes
+necessitates copying it, so it can fail if no other space is available.
If the new size you specify is the same as the old size, @code{realloc}
is guaranteed to change nothing and return the same address that you gave.
@@ -404,10 +407,18 @@ calloc (size_t count, size_t eltsize)
@}
@end smallexample
+But in general, it is not guaranteed that @code{calloc} calls
+@code{malloc} internally. Therefore, if an application provides its own
+@code{malloc}/@code{realloc}/@code{free} outside the C library, it
+should always define @code{calloc}, too.
+
@node Efficiency and Malloc
@subsection Efficiency Considerations for @code{malloc}
@cindex efficiency and @code{malloc}
+@ignore
+
+@c No longer true, see below instead.
To make the best use of @code{malloc}, it helps to know that the GNU
version of @code{malloc} always dispenses small amounts of memory in
blocks whose sizes are powers of two. It keeps separate pools for each
@@ -433,6 +444,24 @@ time using it. Also, large blocks are normally fewer in number.
Therefore, for large blocks, it makes sense to use a method which takes
more time to minimize the wasted space.
+@end ignore
+
+As apposed to other versions, the @code{malloc} in GNU libc does not
+round up block sizes to powers of two, neither for large nor for small
+sizes. Neighboring chunks can be coalesced on a @code{free} no matter
+what their size is. This makes the implementation suitable for all
+kinds of allocation patterns without generally incurring high memory
+waste through fragmentation.
+
+Very large blocks (much larger than a page) are allocated with
+@code{mmap} (anonymous or via @code{/dev/zero}) by this implementation.
+This has the great advantage that these chunks are returned to the
+system immediately when they are freed. Therefore, it cannot happen
+that a large chunk becomes ``locked'' in between smaller ones and even
+after calling @code{free} wastes memory. The size threshold for
+@code{mmap} to be used can be adjusted with @code{mallopt}. The use of
+@code{mmap} can also be disabled completely.
+
@node Aligned Memory Blocks
@subsection Allocating Aligned Memory Blocks
@@ -440,10 +469,10 @@ more time to minimize the wasted space.
@cindex alignment (with @code{malloc})
@pindex stdlib.h
The address of a block returned by @code{malloc} or @code{realloc} in
-the GNU system is always a multiple of eight. If you need a block whose
-address is a multiple of a higher power of two than that, use
-@code{memalign} or @code{valloc}. These functions are declared in
-@file{stdlib.h}.
+the GNU system is always a multiple of eight (or sixteen on 64-bit
+systems). If you need a block whose address is a multiple of a higher
+power of two than that, use @code{memalign} or @code{valloc}. These
+functions are declared in @file{stdlib.h}.
With the GNU library, you can use @code{free} to free the blocks that
@code{memalign} and @code{valloc} return. That does not work in BSD,
@@ -454,9 +483,9 @@ however---BSD does not provide any way to free such blocks.
@deftypefun {void *} memalign (size_t @var{boundary}, size_t @var{size})
The @code{memalign} function allocates a block of @var{size} bytes whose
address is a multiple of @var{boundary}. The @var{boundary} must be a
-power of two! The function @code{memalign} works by calling
-@code{malloc} to allocate a somewhat larger block, and then returning an
-address within the block that is on the specified boundary.
+power of two! The function @code{memalign} works by allocating a
+somewhat larger block, and then returning an address within the block
+that is on the specified boundary.
@end deftypefun
@comment malloc.h stdlib.h
@@ -475,6 +504,42 @@ valloc (size_t size)
@c !!! xref getpagesize
@end deftypefun
+@node Malloc Tunable Parameters
+@subsection Malloc Tunable Parameters
+
+You can adjust some parameters for dynamic memory allocation with the
+@code{mallopt} function. This function is the general SVID/XPG
+interface, defined in @file{malloc.h}.
+@pindex malloc.h
+
+@deftypefun int mallopt (int @var{param}, int @var{value})
+When calling @code{mallopt}, the @var{param} argument specifies the
+parameter to be set, and @var{value} the new value to be set. Possible
+choices for @var{param}, as defined in @file{malloc.h}, are:
+
+@table @code
+@item M_TRIM_THRESHOLD
+This is the minimum size (in bytes) of the top-most, releaseable chunk
+that will cause @code{sbrk} to be called with a negative argument in
+order to return memory to the system.
+@item M_TOP_PAD
+This parameter determines the amount of extra memory to obtain from the
+system when a call to @code{sbrk} is required. It also specifies the
+number of bytes to retain when shrinking the heap by calling @code{sbrk}
+with a negative argument. This provides the necessary hysteresis in
+heap size such that excessive amounts of system calls can be avoided.
+@item M_MMAP_THRESHOLD
+All chunks larger than this value are allocated outside the normal
+heap, using the @code{mmap} system call. This way it is guaranteed
+that the memory for these chunks can be returned to the system on
+@code{free}.
+@item M_MMAP_MAX
+The maximum number of chunks to allocate with @code{mmap}. Setting this
+to zero disables all use of @code{mmap}.
+@end table
+
+@end deftypefun
+
@node Heap Consistency Checking
@subsection Heap Consistency Checking
@@ -636,44 +701,62 @@ installing such hooks.
@cindex allocation statistics
You can get information about dynamic storage allocation by calling the
-@code{mstats} function. This function and its associated data type are
-declared in @file{malloc.h}; they are a GNU extension.
+@code{mallinfo} function. This function and its associated data type
+are declared in @file{malloc.h}; they are an extension of the standard
+SVID/XPG version.
@pindex malloc.h
@comment malloc.h
@comment GNU
-@deftp {Data Type} {struct mstats}
+@deftp {Data Type} {struct mallinfo}
This structure type is used to return information about the dynamic
storage allocator. It contains the following members:
@table @code
-@item size_t bytes_total
-This is the total size of memory managed by @code{malloc}, in bytes.
+@item int arena
+This is the total size of memory allocated with @code{sbrk} by
+@code{malloc}, in bytes.
+
+@item int ordblks
+This is the number of chunks not in use. (The storage allocator
+internally gets chunks of memory from the operating system, and then
+carves them up to satisfy individual @code{malloc} requests; see
+@ref{Efficiency and Malloc}.)
+
+@item int smblks
+This field is unused.
+
+@item int hblks
+This is the total number of chunks allocated with @code{mmap}.
+
+@item int hblkhd
+This is the total size of memory allocated with @code{mmap}, in bytes.
+
+@item int usmblks
+This field is unused.
-@item size_t chunks_used
-This is the number of chunks in use. (The storage allocator internally
-gets chunks of memory from the operating system, and then carves them up
-to satisfy individual @code{malloc} requests; see @ref{Efficiency and
-Malloc}.)
+@item int fsmblks
+This field is unused.
-@item size_t bytes_used
-This is the number of bytes in use.
+@item int uordblks
+This is the total size of memory occupied by chunks handed out by
+@code{malloc}.
+
+@item int fordblks
+This is the total size of memory occupied by free (not in use) chunks.
-@item size_t chunks_free
-This is the number of chunks which are free -- that is, that have been
-allocated by the operating system to your program, but which are not
-now being used.
+@item int keepcost
+This is the size of the top-most, releaseable chunk that normally
+borders the end of the heap (i.e. the ``brk'' of the process).
-@item size_t bytes_free
-This is the number of bytes which are free.
@end table
@end deftp
@comment malloc.h
-@comment GNU
-@deftypefun {struct mstats} mstats (void)
+@comment SVID
+@deftypefun {struct mallinfo} mallinfo (void)
This function returns information about the current dynamic memory usage
-in a structure of type @code{struct mstats}.
+in a structure of type @code{struct mallinfo}.
@end deftypefun
@node Summary of Malloc
@@ -706,6 +789,9 @@ Allocate a block of @var{size} bytes, starting on a page boundary.
Allocate a block of @var{size} bytes, starting on an address that is a
multiple of @var{boundary}. @xref{Aligned Memory Blocks}.
+@item int mallopt (int @var{param}, int @var{value})
+Adjust a tunable parameter. @xref{Malloc Tunable Parameters}
+
@item int mcheck (void (*@var{abortfn}) (void))
Tell @code{malloc} to perform occasional consistency checks on
dynamically allocated memory, and to call @var{abortfn} when an
@@ -720,7 +806,7 @@ A pointer to a function that @code{realloc} uses whenever it is called.
@item void (*__free_hook) (void *@var{ptr})
A pointer to a function that @code{free} uses whenever it is called.
-@item struct mstats mstats (void)
+@item struct mallinfo mallinfo (void)
Return information about the current dynamic memory usage.
@xref{Statistics of Malloc}.
@end table
@@ -1744,10 +1830,13 @@ If enough memory is not available, this function returns a null pointer
and does not modify @code{*@var{handleptr}}.
@end deftypefun
-@node Memory Warnings
-@section Memory Usage Warnings
-@cindex memory usage warnings
-@cindex warnings of memory almost full
+@ignore
+@comment No longer available...
+
+@comment @node Memory Warnings
+@comment @section Memory Usage Warnings
+@comment @cindex memory usage warnings
+@comment @cindex warnings of memory almost full
@pindex malloc.c
You can ask for warnings as the program approaches running out of memory
@@ -1757,7 +1846,7 @@ system. This is a GNU extension declared in @file{malloc.h}.
@comment malloc.h
@comment GNU
-@deftypefun void memory_warnings (void *@var{start}, void (*@var{warn-func}) (const char *))
+@comment @deftypefun void memory_warnings (void *@var{start}, void (*@var{warn-func}) (const char *))
Call this function to request warnings for nearing exhaustion of virtual
memory.
@@ -1775,3 +1864,5 @@ Normally it ought to display the string for the user to read.
The warnings come when memory becomes 75% full, when it becomes 85%
full, and when it becomes 95% full. Above 95% you get another warning
each time memory usage increases.
+
+@end ignore