Improve alignment of malloc block discussion.
authorrms <rms>
Sun, 25 Oct 1992 00:20:45 +0000 (00:20 +0000)
committerrms <rms>
Sun, 25 Oct 1992 00:20:45 +0000 (00:20 +0000)
Free can now sometimes return space to system.
Discuss freeing valloc blocks.
(valloc): Delete incorrect stuff in valloc about getting page size.
(mcheck): Explain calling mcheck too late.
(mstats): Fix syntax.
(Obstacks): Clean up menu.
(alloca): Explain problem in args of function call.

manual/memory.texi

index 82ad52f..e19e007 100644 (file)
@@ -231,11 +231,11 @@ savestring (const char *ptr, size_t len)
 @}
 @end example
 
-@c !!! 8 is not a magic number; it will vary among machines.
 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, this means the
-address is always a multiple of eight.  Only rarely is any higher
-boundary (such as a page boundary) necessary; for those cases, use
+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}).
 
 Note that the memory located after the end of the block is likely to be
@@ -297,21 +297,15 @@ free_chain (struct chain *chain)
 @}
 @end example
 
-@c !!! this paragraph is totally bogus.
-@c Firstly, it is false.  Secondly, it talks about implementation
-@c details which might very well change in the future; this is a Really
-@c Bad Idea.  Remove this paragraph and the next;
-@c instead say you needn't bother freeing at the end of the program
-@c because the program's storage is all returned to the system on exit.
-You cannot reduce the total memory space used by the program by calling
-@code{free}, because @code{free} does not currently know how to return the
-memory to the operating system.  The purpose of calling @code{free} is to
-allow a later later call to @code{malloc} to reuse the space.  In the mean
-time, the space remains in your program as part of a free-list used
-internally by @code{malloc}.
-
-Therefore, there is no point in freeing blocks at the end of a program,
-when you are not going to allocate any more.
+Occasionally, @code{free} can actually return memory to the operating
+system and make the process smaller.  Usually, all it can do is allow a
+later later call to @code{malloc} to reuse the space.  In the mean time,
+the space remains in your program as part of a free-list used internally
+by @code{malloc}.
+
+There is no point in freeing blocks at the end of a program, because all
+of the program's space is given back to the system when the process
+terminates.
 
 @node Changing Block Size
 @subsection Changing the Size of a Block
@@ -443,8 +437,9 @@ 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}.
 
-@c !!! should say you can use free on blocks from memalign or valloc.
-@c You @strong{cannot} free such blocks in BSD.
+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,
+however---BSD does not provide any way to free such blocks.
 
 @comment malloc.h stdlib.h
 @comment BSD
@@ -460,11 +455,7 @@ address within the block that is on the specified boundary.
 @comment BSD
 @deftypefun {void *} valloc (size_t @var{size})
 Using @code{valloc} is like using @code{memalign} and passing the page size
-as the value of the second argument.  Its advantage is that you don't need
-to determine the page size explicitly (something which cannot be done
-portably).
-@c !!! bogus; valloc(size) == memalign(size, getpagesize())
-@c and the library defines getpagesize.
+as the value of the second argument.
 @end deftypefun
 
 @node Heap Consistency Checking
@@ -488,13 +479,16 @@ past the end of a block that was allocated with @code{malloc}.
 The @var{abortfn} argument is the function to call when an inconsistency
 is found.  If you supply a null pointer, the @code{abort} function is
 used.
-@end deftypefun
 
-Since other library functions (such as the standard I/O functions) may
-call @code{malloc}, you should do @code{mcheck} before anything else in
-your program.  To do this automatically, link with @samp{-lmcheck}.
-@c !!! say great lossage will result otherwise if malloc is called
-@c before mcheck.
+@c ??? That is not true yet--malloc needs to be changed.
+It is too late to begin allocation checking once you have allocated
+anything with @code{malloc}.  So @code{mcheck} does nothing in that
+case.  The function returns @code{-1} if you call it too late, and
+@code{0} otherwise (when it is successful).
+
+The easiest way to arrange to call @code{mcheck} early enough is to use
+the option @samp{-lmcheck} when you link your program.
+@end deftypefun
 
 @node Hooks for Malloc
 @subsection Storage Allocation Hooks
@@ -578,7 +572,8 @@ main ()
 The @code{mcheck} function (@pxref{Heap Consistency Checking}) works by
 installing such hooks.
 
-@c !!! __morecore, __after_morecore_hook are undocumented
+@c __morecore, __after_morecore_hook are undocumented
+@c It's not clear whether to document them.
 
 @node Statistics of Malloc
 @subsection Statistics for Storage Allocation with @code{malloc}
@@ -620,9 +615,7 @@ This is the number of bytes which are free.
 
 @comment malloc.h
 @comment GNU
-@c !!! in the printed manual, the 1st `mstats' got bolded; the 2nd
-@c should have been instead.
-@deftypefun struct mstats mstats (void)
+@deftypefun {struct mstats} mstats (void)
 This function returns information about the current dynamic memory usage
 in a structure of type @code{struct mstats}.
 @end deftypefun
@@ -705,15 +698,11 @@ the padding needed to start each object on a suitable boundary.
                                 complicated) growing objects.
 * Status of an Obstack::        Inquiries about the status of an obstack.
 * Obstacks Data Alignment::     Controlling alignment of objects in obstacks.
-* Obstack Chunks::              How obstacks obtain and release chunks
-                               Efficiency considerations.
+* Obstack Chunks::              How obstacks obtain and release chunks;
+                                efficiency considerations.
 * Summary of Obstacks::         
 @end menu
 
-@c !!! something about the above menu looks strange; the description
-@c "Efficiency considerations" is capitalized, but doesn't go with
-@c anything.  Is it part of the above description?
-
 @node Creating Obstacks
 @subsection Creating Obstacks
 
@@ -1403,9 +1392,12 @@ bytes of storage, allocated in the stack frame of the calling function.
 @end deftypefun
 
 Do not use @code{alloca} inside the arguments of a function call---you
-will get unpredictable results.  An example of what to avoid is
-@code{foo (x, alloca (4), y)}.
-@c !!! does this really lose?  Why? -rm
+will get unpredictable results, because the stack space for the
+@code{alloca} would appear on the stack in the middle of the space for
+the function arguments.  An example of what to avoid is @code{foo (x,
+alloca (4), y)}.
+@c This might get fixed in future versions of GCC, but that won't make
+@c it safe with compilers generally.
 
 @menu
 * Alloca Example::              Example of using @code{alloca}.