Message-ID: <3EB17A90.96CB9465@yahoo.com> Date: Thu, 01 May 2003 15:50:40 -0400 From: CBFalconer Organization: Ched Research X-Mailer: Mozilla 4.75 [en] (Win98; U) X-Accept-Language: en MIME-Version: 1.0 To: djgpp-workers AT delorie DOT com Subject: Re: nmalloc documentation revisions References: <3EAF5020 DOT 9E3C6C9A AT yahoo DOT com> <7458-Wed30Apr2003210444+0300-eliz AT elta DOT co DOT il> <3EB08219 DOT 3D55D32A AT yahoo DOT com> <7458-Thu01May2003192021+0300-eliz AT elta DOT co DOT il> Content-Type: text/plain; charset=us-ascii Content-Transfer-Encoding: 7bit Reply-To: djgpp-workers AT delorie DOT com Eli Zaretskii wrote: > > From: CBFalconer > > > > > > Also, please produce the diffs like this: > > > > > > diff -c malloc.txh nmalloc.txh > > > > > > Note the "-c" switch--it's very important. > > > > Sigh. I guess I have been too used to being chief honcho :-) > > Try this. > > Thanks. Here are my comments: > > > ! The size of the currently available top portion of the memory > > ! assigned by sbrk. Sometimes known as 'slop'. > > Please change the last sentence into this: > > Sometimes known as @dfn{slop}. > ... snip ... > > > ! This function allows diverting the output of the malldbg package > > ! to any suitable text file. By default the package uses stderr. > > ``stderr'' is a symbol, so should be in @code{}. > > > ! The ohead value is not useful in the present > > ! implementation. > > Please put ``ohead'' and other struct members in @code{}. > > Last but not least, thanks for working on this. You are a hard taskmaster. I suspect you have very well behaved dogs :-) Of course your message arrived here just after I uploaded the complete package! Good old Murphy. BTW, I have been doing some thinking about a 'small allocations' provision, and I may have come up with a reasonable method. However such things would not be tracked by the malldbg package, and would probably be slower. I have doubts as to the utility of such. Here is the diff from the nmalloc.txh (now .txo) mounted on my site: *** nmalloc.txo Wed Apr 30 21:32:22 2003 --- nmalloc.txh Thu May 1 15:38:42 2003 *************** *** 178,202 **** @itemx hblkhd The size of the currently available top portion of the memory ! assigned by sbrk. Sometimes known as 'slop'. @item usmblks The space (in bytes) in ``small blocks'' that are in use. This is always zero in the DJGPP implementation. @item fsmblks ! The space in free ``small blocks''. Normally zero in this implementation. @item uordblks ! The amount of space, in bytes, in the heap space currently used by the ! application. This does not include the small overhead (8 bytes per ! block) used by @code{malloc} to maintain its hidden information in each allocated block. @item fordblks ! The amount of free heap space maintained by @code{malloc} in its free ! list. @item keepcost The total overhead used by @code(malloc) in maintaining the --- 178,202 ---- @itemx hblkhd The size of the currently available top portion of the memory ! assigned by @code(sbrk). Sometimes known as @dfn(slop). @item usmblks The space (in bytes) in ``small blocks'' that are in use. This is always zero in the DJGPP implementation. @item fsmblks ! The space in free ``small blocks''. Normally zero in the DJGPP implementation. @item uordblks ! The amount of space, in bytes, in the heap space currently used ! by the application. This does not include the small overhead ! used by @code{malloc} to maintain its hidden information in each allocated block. @item fordblks ! The amount of free heap space maintained by @code{malloc} in its ! free list of hblks chunks. @item keepcost The total overhead used by @code(malloc) in maintaining the *************** *** 235,257 **** @end example @subheading Description ! ! This function attempts to determine if the heap has been corrupted. It ! scans all the blocks allocated by @code{malloc} and handed to the ! application, and also all the free blocks maintained by @code{malloc} ! and @code{free} in the internal free list. Each block is checked for ! consistency of the hidden bookkeeping information recorded in it by ! @code{malloc} and @code{free}. What happens when a bad block is found depends on the current ! @dfn{malloc diagnostics level}: for example, the block can be reported, ! or the program may be aborted. @xref{malloc_debug}, for the details. @subheading Return Value ! ! If the program isn't aborted during the function's run (this depends on ! the current diagnostics level), @code{malloc_verify} returns 1 if the ! heap passes all tests, or zero of some of the tests failed. @subheading Portability --- 235,258 ---- @end example @subheading Description ! This function attempts to determine if the heap has been ! corrupted. It scans all the blocks allocated by @code{malloc} ! and handed to the application, and also all the free blocks ! maintained by @code{malloc} and @code{free} in the internal free ! list. Each block is checked for consistency of the hidden ! bookkeeping information recorded in it by @code{malloc} and ! @code{free}. What happens when a bad block is found depends on the current ! @dfn{malloc diagnostics level}: for example, the block can be ! reported, or the program may be aborted. @xref{malloc_debug}, ! for the details. @subheading Return Value ! If the program isn't aborted during the function's run (this ! depends on the current diagnostics level), @code{malloc_verify} ! returns 1 if the heap passes all tests, or zero of some of the ! tests failed. @subheading Portability *************** *** 278,325 **** @end example @subheading Description ! ! This function sets the level of error diagnosis and reporting during ! subsequent calls to @code{malloc}, @code{free}, @code{realloc}, and all ! functions which call them internally. The argument @var{level} is ! interpreted as follows: @table @asis @item Level 0 The memory allocation functions behave as they do if @code{malloc_debug} was never called. Only passive checks are ! allowed, including malloc_verify, mallocmap, and malldbgdumpfile ! (to set the output file). In particular mallsethook() is ! disabled, to avoid accidents. The actual functioning of the ! malloc system remains unaffected. Any malloc hooks are reset. ! If errors are detected by @code{malloc_verify}, it prints ! diagnostic messages to the dumpfile (default standard error ! stream), with address and size of the offending block and other ! pertinent information. @item Level 1 All the passive checks of level 0 are allowed. In addition ! mallsethook() is enabled, thus allowing construction of custom ! debugging packages. @item Level 2 Similar to level 1, but the consistency of the entire heap is also verified (by calling @code{malloc_verify}) on every call to the memory allocation functions. @emph{Warning: this may significantly slow down the application.} Since the malloc ! hooks are in use to connect to this system, mallsethook is ! disabled. If there are hooks already in use the change to level ! 2 or above is rejected. @item Level 3 ! Like level 2, except that the program is aborted whenever a heap ! corruption is detected. In addition, failed allocations (i.e.@: when ! @code{malloc} returns @code{NULL} because it cannot satisfy a request) ! are reported to the dumpfile (default standard error). @item Level 4 ! Like level 3, but calls to @code{free} with a @code{NULL} pointer as an ! argument are also reported. @item Level -1 Does not alter the debug level, but returns the current value. --- 279,327 ---- @end example @subheading Description ! This function sets the level of error diagnosis and reporting ! during subsequent calls to @code{malloc}, @code{free}, ! @code{realloc}, and all functions which call them internally. ! The argument @var{level} is interpreted as follows: @table @asis @item Level 0 The memory allocation functions behave as they do if @code{malloc_debug} was never called. Only passive checks are ! allowed, including @code(malloc_verify), @code(mallocmap), and ! @code(malldbgdumpfile) (to set the output file). In particular ! @code(mallsethook) is disabled, to avoid accidents. The actual ! functioning of the malloc system remains unaffected. Any malloc ! hooks @xref(mallsethook) are reset. If errors are detected by ! @code{malloc_verify}, it prints diagnostic messages to the ! @defn(dumpfile) (default standard error stream), with address ! and size of the offending block and other pertinent information. @item Level 1 All the passive checks of level 0 are allowed. In addition ! @code(mallsethook) is enabled, thus allowing construction of ! custom debugging packages. @item Level 2 Similar to level 1, but the consistency of the entire heap is also verified (by calling @code{malloc_verify}) on every call to the memory allocation functions. @emph{Warning: this may significantly slow down the application.} Since the malloc ! hooks are in use to connect to this system, @code(mallsethook) ! is disabled. If there are hooks already in use the change to ! level 2 or above is rejected. @item Level 3 ! ! Similar to level 2, except that the program is aborted whenever ! a heap corruption is detected. In addition, failed allocations ! (i.e.@: when @code{malloc} returns @code{NULL} because it cannot ! satisfy a request) are reported to the dumpfile (default ! standard error). @item Level 4 ! Similar to level 3, but calls to @code{free} with a @code{NULL} ! pointer as an argument are also reported. @item Level -1 Does not alter the debug level, but returns the current value. *************** *** 358,366 **** @subheading Description This function prints a map of the heap storage to the selected ! dumpfile. (See malldbgdumpfile). For each block, its address and ! size are printed, as well as an indication whether it is free or ! in use, together with pointers to adjacent blocks. @subheading Return Value --- 360,368 ---- @subheading Description This function prints a map of the heap storage to the selected ! @file(dumpfile). @xref(malldbgdumpfile). For each block, its ! address and size are printed, as well as an indication whether ! it is free or in use, together with pointers to adjacent blocks. @subheading Return Value *************** *** 385,434 **** @end example @subheading Description ! ! These hooks are provided for building custom @code{malloc} ! debugging packages. Such packages typically need to be notified ! when memory is allocated and freed by the application, in order ! to be able to find memory leaks, code that writes beyond the ! limits of allocated buffers or attempts to free buffers which ! were not allocated by @code{malloc}, etc. These hooks can be ! used to define callback functions which will be called by the ! library at strategic points. Each callback is only called if it ! is non- AT code{NULL}; by default, all of them are initialized to a ! @code{NULL} value. The actual hook to be set is described by the following ! constants, enumerated in stdlib.h: ! malloc_HK = 0 on entry to malloc ! malloc_fail_HK when malloc fails ! free_HK on entry to free ! free_null_HK when free is called with a NULL pointer ! realloc_HK on entry to realloc ! realloc_exit_HK when realloc exits. ! HKCOUNT The first invalid value for a hook descriptor. and each ``callback'' function is described by: typedef void (*M_HOOKFN)(size_t sz, void *ptr); ! in stdlib.h. Note that in some cases the parameters supplied to ! the ``callback'' function will be meaningless, in which case ! they will be zero or NULL as appropriate. The callback function ! must NOT call any of malloc, free, or realloc. ! ! mallsethook action is disabled unless the debug_level is set to ! 1. This interlock avoids accidental use before enabling the ! package, and avoids altering hooks that are already in use for ! debug_level of 2 or higher. For access to the internal storage of the malloc arena, see the ! _sysmalloc() call and the _sysinfo struct. @table @code @item malloc_HK - Called just before a chunk of memory is about to be returned to the application in response to an allocation request. @var{sz} is the size requested by the application --- 387,453 ---- @end example @subheading Description ! Several @defn(hooks) are provided for building custom ! @code{malloc} debugging packages. Such packages typically need ! to be notified when memory is allocated and freed by the ! application, in order to be able to find memory leaks, code that ! writes beyond the limits of allocated buffers or attempts to ! @code(free) buffers which were not allocated by @code{malloc}, ! etc. These hooks can be used to define callback functions which ! will be called by the library at strategic points. Each ! callback is only called if it is non- AT code{NULL}; by default, ! all of them are initialized to a @code{NULL} value. The actual hook to be set is described by the following ! constants, enumerated in @file(stdlib.h): ! ! @table @code ! @item malloc_HK = 0 ! on entry to malloc ! ! @item malloc_fail_HK ! when malloc fails ! ! @item free_HK ! on entry to free ! ! @item free_null_HK ! when free is called with a NULL pointer ! @item realloc_HK ! on entry to realloc ! ! @item realloc_exit_HK ! when realloc exits. ! ! @item HKCOUNT ! The first invalid value for a hook descriptor. ! @end @table and each ``callback'' function is described by: + @example typedef void (*M_HOOKFN)(size_t sz, void *ptr); + @end ! @noindent ! in @file(stdlib.h). Note that in some cases the parameters ! supplied to the ``callback'' function will be meaningless, in ! which case they will be zero or @code(NULL) as appropriate. The ! callback function must @strong(NOT) call any of @code(malloc), ! @code(free), or @code(realloc). ! ! @code(mallsethook) action is disabled unless the debug_level is ! set to 1. This interlock avoids accidental use before enabling ! the package, and avoids altering hooks that are already in use ! for debug_level of 2 or higher. For access to the internal storage of the malloc arena, see the ! @code(_sysmalloc) call and the @code(_sysinfo) struct. @table @code @item malloc_HK Called just before a chunk of memory is about to be returned to the application in response to an allocation request. @var{sz} is the size requested by the application *************** *** 437,456 **** allocated. @item malloc_fail_HK - Called if @code{malloc} failed to find a free block large enough to satisfy a request, and also failed to obtain additional memory from @code{sbrk}. @var{sz} is the requested allocation size. @item free_HK - Called when a buffer is about to be freed. @var{ptr} is a pointer to the block to be freed. Its validity has not been checked. @item free_null_HK - Called whenever a @code{NULL} pointer is passed to @code{free}. @acronym{ANSI} C specifically rules that this is allowed and should have no effect, but you might want to catch such cases if --- 456,472 ---- *************** *** 458,464 **** libraries don't like @code{NULL} pointers in @code{free}. @item realloc_HK - Called at entry to @code{realloc}, before the actual reallocation. @var{ptr} is the pointer whose contents are to be reallocated. @var{sz} is the new size requested by the --- 474,479 ---- *************** *** 467,486 **** @code{realloc} calls them.) @item realloc_exit_HK ! ! Called at exit from realloc. @var(sz) is the requested size, ! and @var(ptr) is the (possibly) revised value of the user ! pointer which will be returned my realloc. This may be NULL if ! realloc was unable to allocate the space, in which case ONLY the ! original value of @var(ptr) (as reported by realloc_HK) remains ! valid. @end table @subheading Return Value @code{mallsethook} returns the previous hook pointer, (usually ! NULL). If mallsethook is disabled it will also return NULL @subheading Portability --- 482,501 ---- @code{realloc} calls them.) @item realloc_exit_HK ! Called at exit from @code(realloc). @var(sz) is the requested ! size, and @var(ptr) is the (possibly) revised value of the user ! pointer which will be returned by @code(realloc). This may be ! @code(NULL) if realloc was unable to allocate the space, in ! which case @emph(ONLY) the original value of @var(ptr) (as ! reported by @code(realloc_HK)) remains valid. @end table @subheading Return Value @code{mallsethook} returns the previous hook pointer, (usually ! @code(NULL)). If @code(mallsethook) is disabled it will also ! return @code(NULL). @subheading Portability *************** *** 519,525 **** @subheading Description This function allows diverting the output of the malldbg package ! to any suitable text file. By default the package uses stderr. @subheading Return Value --- 534,541 ---- @subheading Description This function allows diverting the output of the malldbg package ! to any suitable text file, known as the @defn(dumpfile). By ! default the package uses @file(stderr). @subheading Return Value *************** *** 560,566 **** @subheading Return Value ! A struct _sysquery, described as follows: @example struct _sysquery @{ --- 576,582 ---- @subheading Return Value ! A @code(struct _sysquery), described as follows: @example struct _sysquery @{ *************** *** 571,597 **** @}; @end example ! Any unsigned char field set to 255 signifies the value is ! meaningless. The ohead value is not useful in the present ! implementation. The remaining values are small offsets from the ! internal pointers to the appropriate fields. In particular ! data is the offset between the internal pointer and the user ! pointers. nxt and prv link all allocated memory blocks, while ! nxtf and prvf are used only to link free blocks. sz is the ! internal size of the block, not the user size, and is normally ! rounded upward. Thus the nxt field is redundant to the sz field ! (except when no nxt exists) and is used in validity checking. ! A null value in nxtf field signifies that the block is not free. ! The special value nilp is used in nxtf and prvf as a NULL value ! distinguishable from NULL. ! ! anchors points to a NULL terminated list of sets of chains of ! memory blocks. These were allocated by sbrk and were not ! contiguous to any previous allocations. ! ! hookset is a pointer to a function that can set malloc hooks, as ! described in mallsethook. It is only available through this ! link. @subheading Portability --- 587,615 ---- @}; @end example ! Any unsigned char field set to 255 signifies the value is ! meaningless. The @code(ohead) value is not useful in the ! present implementation. The remaining values are small offsets ! from the internal pointers to the appropriate fields. In ! particular @code(data) is the offset between the internal ! pointer and the user pointers. @code(nxt) and @code(prv) link ! all allocated memory blocks, while @code(nxtf) and @code(prvf) ! are used only to link free blocks. @code(sz) is the internal ! size of the block, not the user size, and is normally rounded ! upward. Thus the @code(nxt) field is redundant to the @code(sz) ! field (except when no @code(nxt) exists) and is used in validity ! checking. A @code(NULL) value in @code(nxtf) field signifies ! that the block is not free. The special value @code(nilp) is ! used in @code(nxtf) and @code(prvf) as a @code(NULL) value ! distinguishable from @code(NULL). ! ! anchors points to a @code(NULL) terminated list of sets of ! chains of memory blocks. These were allocated by @code(sbrk) ! and were not contiguous to any previous allocations. ! ! @code(hookset) is a pointer to a function that can set malloc ! hooks, as described in @code(mallsethook). It is only available ! through this link. @subheading Portability -- Chuck F (cbfalconer AT yahoo DOT com) (cbfalconer AT worldnet DOT att DOT net) Available for consulting/temporary embedded and systems. USE worldnet address!