summary refs log tree commit diff
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.tar.gz
glibc-c131718ccc1db101df54fb04f34f5611c3678450.tar.xz
glibc-c131718ccc1db101df54fb04f34f5611c3678450.zip
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 9ebe31e920..16dc9aa5e1 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