Message-ID: <3EA82F6D.40414228@yahoo.com>
Date: Thu, 24 Apr 2003 14:39:41 -0400
From: CBFalconer <cbfalconer AT yahoo DOT com>
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 revisited
References: <200304231105 DOT NAA07336 AT lws256 DOT lu DOT erisoft DOT se> <3EA67D55 DOT 63EF458C AT phekda DOT freeserve DOT co DOT uk> <3EA69078 DOT 48E745D9 AT yahoo DOT com> <3EA783FC DOT C4BEA2BD AT yahoo DOT com>
Content-Type: text/plain; charset=us-ascii
Content-Transfer-Encoding: 7bit
Reply-To: djgpp-workers AT delorie DOT com

Following is a horrible hackup of the malloc.txh file.  Maybe
someone who knows what they are doing can clean it up somewhat and
return it to me, and I can then try to maintain the internal
components. Hack follows:

@node malloc, memory
@subheading Syntax

@example
#include <stdlib.h>

void *malloc(size_t size);
@end example

@subheading Description

This function allocates a chunk of memory from the heap large
enough to hold any object that is @var{size} bytes in length.
This memory must be returned to the heap with @code{free}
(@pxref{free}).

Note: this version of malloc is designed to reduce memory usage.
A faster but less efficient version is available in the libc
sources (@file{djlsr*.zip}) in the file
@file{src/libc/ansi/stdlib/fmalloc.c}.

@subheading Return Value

A pointer to the allocated memory, or @code{NULL} if there isn't
enough free memory to satisfy the request.

@subheading Portability

@portability ansi, posix

@subheading Example

@example
char *c = (char *)malloc(100);
@end example

@c -------------------------------------------------------------

@node free, memory
@subheading Syntax

@example
#include <stdlib.h>

void free(void *ptr);
@end example

@subheading Description

Returns the allocated memory to the heap (@pxref{malloc}).  If
the @var{ptr} is @code{NULL}, @code{free} does nothing. 

@subheading Return Value

None.

@subheading Portability

@portability ansi, posix

@subheading Example

@example
char *q = (char *)malloc(20);
free(q);
@end example

@c -------------------------------------------------------------

@node realloc, memory
@subheading Syntax

@example
#include <stdlib.h>

void *realloc(void *ptr, size_t size);
@end example

@subheading Description

This function changes the size of the region pointed to by
@var{ptr}. If it can, it will reuse the same memory space, but
it may have to allocate a new memory space to satisfy the
request.  In either case, it will return the pointer that you
should use to refer to the (possibly new) memory area.  The
pointer passed may be @code{NULL}, in which case this function
acts just like @code{malloc} (@pxref{malloc}).

An application that wants to be robust in the face of a possible
failure of @code{realloc} to enlarge a buffer should save a copy
of the old pointer in a local variable, to be able to use the
original buffer in case @code{realloc} returns @code{NULL}.  See
the example below for details.

@subheading Return Value

On success, a pointer is returned to the memory you should now
refer to.  On failure, @code{NULL} is returned and the memory
pointed to by @var{ptr} prior to the call is not freed.

@subheading Portability

@portability ansi, posix

@subheading Example

@example
if (now+new > max)
@{
  char *old = p;

  max = now+new;
  p = realloc(p, max);
  if (p == NULL)
    p = old;  /* retain the old pointer */
@}
@end example

@c -------------------------------------------------------------

@node mallinfo, memory
@subheading Syntax

@example
#include <malldbg.h>

struct mallinfo mallinfo(void);
@end example

@subheading Description

This function returns information about heap space usage.  It is
intended to be used for debugging dynamic memory allocation and
tracking heap usage.  The @code{struct mallinfo} structure is
defined by @file{stdlib.h} as follows:

@example
 struct mallinfo @{
   int arena;
   int ordblks;
   int smblks;
   int hblks;
   int hblkhd;
   int usmblks;
   int fsmblks;
   int uordblks;
   int fordblks;
   int keepcost;
 @};
@end example

@noindent
whose members are:

@table @code
@item arena
The total amount of space, in bytes, handed by @code{sbrk} to
@code{malloc}.  Note that this is not the same as
@code{sbrk(0)}, since @code{sbrk} allocates memory in large
chunks and then subdivides them and passes them to @code{malloc}
as required.  In particular, the result of @code{sbrk(0)} might
be much larger than the @code{arena} member of @code{struct
mallinfo} when the DPMI host allocates memory in non-contiguous
regions (happens on MS-Windows).

@item ordblks
The number of ``ordinary blocks'': the total number of allocated
and free blocks maintained by @code{malloc}.

@item smblks
The number of ``small blocks''.  This is normally zero, unless a
different version of @code{malloc} was compiled with the symbol
@code{NUMSMALL} defined to a non-zero value.  Doing so activates
an optional algorithm which serves small allocations quickly
from a special pool.  If this option is activated, the
@code{smblks} member returns the number of free small blocks
(the allocated small blocks are included in the value of
@code{ordblks}).

@item hblks
The number of free blocks currently maintained, including the
``slop'' left from the last system allocation via sbrk().

@itemx hblkhd
The size of the ``slop'' remaining from the last system
allocation via sbrk().

@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''.  Non-zero only if a
different version of @code{malloc} was compiled with
@code{NUMSMALL} defined to a non-zero value.  In that case,
gives the amount of space in bytes in free small blocks.

@item uordblks
The amount of space, in bytes, in the heap space currently used
by the application.  This does not include the small overhead
(16 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 memory overhead used by @code(malloc) in maintaining
its hidden block allocation information.

@end table

@subheading Return Value

The @code{mallinfo} structure filled with information.

@subheading Portability

@port-note posix This function is available on many Unix
systems.  Some field meanings may vary.
@portability !ansi, !posix

@subheading Example

@example
 struct mallinfo info = mallinfo();

 printf("Memory in use: %d bytes\n",
        info.usmblks + info.uordblks);
 printf("Total heap size: %d bytes\n", info.arena);
@end example

@c -------------------------------------------------------------

@node malloc_verify, memory
@subheading Syntax

@example
#include <malldbg.h>

int malloc_verify(void);
@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}.  The blocks on the free list are also validated.

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

@port-note posix This function is available on many Unix systems.
@portability !ansi, !posix

@subheading Example

@example
 if (malloc_verify() == 0)
   printf ("Heap corruption detected!\n");
@end example

@c -------------------------------------------------------------

@node malloc_debug, memory
@subheading Syntax

@example
#include <malldbg.h>

int malloc_debug(int level);
@end example

@subheading Description

This function sets the level of error diagnosis and reporting
during subsequent calls to @code{malloc}, @code{free},
@code{realloc}, @code(malldbgdumpfile), @code(mallsethook) and
all functions which call them internally. The argument
@var{level} is interpreted as follows:

@table @asis
@item Level 0
No checking; the memory allocation functions behave as they do
if @code{malloc_debug} was never called.

@item Level 1
@code{malloc_verify} can test the memory structure for
corruption, even if these blocks were not yet @code{free}d.  If
errors are detected by @code{malloc_verify}, it prints
diagnostic messages to the standard error stream (or such file
as has been designated by @code(malldbgdumpfile)), with address
and size of the offending block and other pertinent information.
The only added overhead is that of actually executing the tests.
@code(mallocmap) may be used to examine the complete memory
arena at any time. In addition the use of @code(mallsethook) is
enabled.  This allows creation of any desired testing interface.

@item Level 2
Like level 1, but in addition the consistency of the entire heap
is verified (by calling @code{malloc_verify}) on every call to
the memory allocation functions.  @emph{Warning: this may
significantly slow down the application.} In addition the use of
@code(mallsethook) is inhibited, because the facility is already
in use.

@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 standard error.

@item Level 4
Like level 3, but calls to @code{free} with a @code{NULL}
pointer as an argument are also reported.
@end table

@subheading Return Value

@code{malloc_debug} returns the previous error diagnostic level.
The default level is 0.

@subheading Portability

@port-note posix This function is available on many Unix systems.
@portability !ansi, !posix

@subheading Example

@example
 malloc_debug(2);
 ...
 malloc_verify();
@end example

@c -------------------------------------------------------------

@node mallocmap, memory
@subheading Syntax

@example
#include <malldbg.h>

void mallocmap(int level);
@end example

@subheading Description

level temporarily overides the currend malloc diagnostics level
for the duration of this call.

This function prints a map of the heap storage to standard
output.  For each block, its address and size are printed, as
well as an indication whether it is free or in use. 

@subheading Return Value

None.

@subheading Portability

@port-note posix This function is available on many Unix systems.
@portability !ansi, !posix

@c -------------------------------------------------------------

@node malloc hook functions, memory
@subheading Syntax

@example
#include <malldbg.h>

M_HOOKFN mallsethook(enum m_hook_kind which,
                     M_HOOKFN         newhook);
@end example

@subheading Description

This is disabled unless the malloc_debug level is 1.

Hooks can be set to call a user supplied routine under various
circumstances.  The user routines will be of the form:

  void userfunction(size_t size, void *ptr);
  
which is a predefined type supplied as M_HOOKFN in malldbg.h  
and can examine its parameters as desired.  The hooks are set
by calling mallsethook with a which parameter selected from the
enumeration m_hook_kind:

@table @asis
@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{size} is the size requested by the application
(@strong{not} the actual size of the allocated buffer, which may
be larger).  @var{ptr} is a pointer to the block that was
allocated.

This hook may also be called when realloc(NULL, size) is called,
when it and realloc_exit_HK may both be energized.

@item malloc_fail_HK
Called at malloc exit ONLY when malloc failed to allocate 
memory.  size is the size requested, and ptr is NULL.

@item free_HK
Called whenever free is called.  size is 0 and meaningless, ptr 
is the value passed to free.  If ptr is valid various fields
can be examined, see _sysmalloc.

@item free_null_HK
As free_HK but called only when a NULL pointer is passed to free.
Advisory only, as no fields of a NULL pointer can be examined.

@item realloc_HK
Called on entry to realloc.  size is the new size requested,
ptr is the pointer passed to realloc.

@item realloc_exit_HK
Called on exit from realloc.  size is the new size requested,
ptr is the value realloc will return.

@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.

Use of information returned by _sysquery allows examination of
the internal arena fields.

@subheading Portability

@portability !ansi, !posix

These hooks are specific to DJGPP.

@c -------------------------------------------------------------

@node malloc hook functions, memory
@subheading Syntax

@example
#include <malldbg.h>

FILE *malldbgdumpfile(FILE *fp);

@end example

@subheading Description

This sets the file on which the package will emit information.
If fp is NULL stderr is used.

Returns the previous setting of the dumpfile.

@subheading Portability

@portability !ansi, !posix

This is specific to DJGPP.

@c -------------------------------------------------------------

@node malloc hook functions, memory
@subheading Syntax

@example
#include <malldbg.h>

struct _sysquery _sysmalloc(void);
@end example

@subheading Description

Returns a structure describing the internal workings of the
malloc arena. struct_sysquery is described in sysquery.h, and 
automatically included in malldbg.h.

@subheading Portability

@portability !ansi, !posix

This is specific to DJGPP.


-- 
Chuck F (cbfalconer AT yahoo DOT com) (cbfalconer AT worldnet DOT att DOT net)
   Available for consulting/temporary embedded and systems.
   <http://cbfalconer.home.att.net>  USE worldnet address!