Source Code 1994 March/Source_Code_CD-ROM_Walnut_Creek_March_1994.iso/compsrcs/unix/volume26/mallc120/part04

Text File | 1993-04-05 | 75.1 KB | 2,216 lines

Newsgroups: comp.sources.unix
From: [e-mail] (Gray Watson)
Subject: v26i101: malloc - debugging version of malloc, V1.2.0, Part04/05
Sender: [e-mail]
Approved: [e-mail]

Submitted-By: [e-mail] (Gray Watson)
Posting-Number: Volume 26, Issue 101
Archive-Name: malloc-1.2.0/part04

#! /bin/sh
# This is a shell archive.  Remove anything before this line, then unpack
# it by saving it into a file and typing "sh file".  To overwrite existing
# files, type "sh file -c".  You can also feed this as standard input via
# unshar, or by typing "sh <file", e.g..  If this archive is complete, you
# will see the following message at the end:
#        "End of archive 4 (of 5)."
# Contents:  chunk.h chunk_loc.h compat.c compat.h conf.h.in
#   malloc.texi malloc_t.c mallocrc
# Wrapped by [e-mail] on Tue Apr  6 01:24:07 1993
PATH=/bin:/usr/bin:/usr/ucb ; export PATH
if test -f 'chunk.h' -a "${1}" != "-c" ; then
  echo shar: Will not clobber existing file \"'chunk.h'\"
else
echo shar: Extracting \"'chunk.h'\" \(2936 characters\)
sed "s/^X//" >'chunk.h' <<'END_OF_FILE'
X/*
X * defines for low level memory management routines
X *
X * Copyright 1992 by Gray Watson and the Antaire Corporation
X *
X * This file is part of the malloc-debug package.
X *
X * This library is free software; you can redistribute it and/or
X * modify it under the terms of the GNU Library General Public
X * License as published by the Free Software Foundation; either
X * version 2 of the License, or (at your option) any later version.
X *
X * This library is distributed in the hope that it will be useful,
X * but WITHOUT ANY WARRANTY; without even the implied warranty of
X * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
X * Library General Public License for more details.
X *
X * You should have received a copy of the GNU Library General Public
X * License along with this library (see COPYING-LIB); if not, write to the
X * Free Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
X *
X * The author of the program may be contacted at [e-mail]
X *
X * $Id: chunk.h,v 1.16 1993/04/05 22:29:57 gray Exp $
X */
X
X#ifndef __CHUNK_H__
X#define __CHUNK_H__
X
X#include "malloc.h"            /* for IMPORT ... */
X
X/* some argument defines */
X#define CHUNK_PNT_ANAL    0        /* anal checking on pointer */
X#define CHUNK_PNT_LOOSE    1        /* looser checking */
X
X/*<<<<<<<<<<  The below prototypes are auto-generated by fillproto */
X
XIMPORT    int        _calloc_count;  /* # callocs, done in alloc */
X
X/*
X * startup the low level malloc routines
X */
XIMPORT    int    _chunk_startup(void);
X
X/*
X * run extensive tests on the entire heap depending on TYPE
X */
XIMPORT    int    _chunk_heap_check(void);
X
X/*
X * run extensive tests on PNT from FUNC. test PNT HOW_MUCH of MIN_SIZE
X * (or 0 if unknown).  returns [NO]ERROR
X */
XIMPORT    int    _chunk_pnt_check(const char * func, char * pnt,
X                 const int check, int min_size);
X
X/*
X * return some information associated with PNT, returns [NO]ERROR
X */
XIMPORT    int    _chunk_read_info(char * pnt, unsigned int * size,
X                 char ** file, unsigned int * line);
X
X/*
X * get a SIZE chunk of memory for FILE at LINE
X */
XIMPORT    char    *_chunk_malloc(const char * file, const unsigned int line,
X                   unsigned int size);
X
X/*
X * frees PNT from the heap, returns FREE_ERROR or FREE_NOERROR
X */
XIMPORT    int    _chunk_free(const char * file, const unsigned int line,
X                char * pnt);
X
X/*
X * reallocate a section of memory
X */
XIMPORT    char    *_chunk_realloc(const char * file, const unsigned int line,
X                char * oldp, unsigned int new_size);
X
X/*
X * log present free and used lists
X */
XIMPORT    void    _chunk_list_count(void);
X
X/*
X * log statistics on the heap
X */
XIMPORT    void    _chunk_stats(void);
X
X/*
X * dump the unfreed memory, logs the unfreed information to logger
X */
XIMPORT    void    _chunk_dump_not_freed(void);
X
X/*
X * log the heap structure plus information on the blocks if necessary
X */
XIMPORT    void    _chunk_log_heap_map(void);
X
X/*<<<<<<<<<<   This is end of the auto-generated output from fillproto. */
X
X#endif /* ! __CHUNK_H__ */
END_OF_FILE
if test 2936 -ne `wc -c <'chunk.h'`; then
    echo shar: \"'chunk.h'\" unpacked with wrong size!
fi
# end of 'chunk.h'
fi
if test -f 'chunk_loc.h' -a "${1}" != "-c" ; then
  echo shar: Will not clobber existing file \"'chunk_loc.h'\"
else
echo shar: Extracting \"'chunk_loc.h'\" \(5339 characters\)
sed "s/^X//" >'chunk_loc.h' <<'END_OF_FILE'
X/*
X * local defines for the low level memory routines
X *
X * Copyright 1992 by Gray Watson and the Antaire Corporation
X *
X * This file is part of the malloc-debug package.
X *
X * This library is free software; you can redistribute it and/or
X * modify it under the terms of the GNU Library General Public
X * License as published by the Free Software Foundation; either
X * version 2 of the License, or (at your option) any later version.
X *
X * This library is distributed in the hope that it will be useful,
X * but WITHOUT ANY WARRANTY; without even the implied warranty of
X * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
X * Library General Public License for more details.
X *
X * You should have received a copy of the GNU Library General Public
X * License along with this library (see COPYING-LIB); if not, write to the
X * Free Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
X *
X * The author of the program may be contacted at [e-mail]
X *
X * $Id: chunk_loc.h,v 1.9 1993/04/05 22:29:58 gray Exp $
X */
X
X#ifndef __CHUNK_LOC_H__
X#define __CHUNK_LOC_H__
X
X/* defines for the malloc subsystem */
X#define BASIC_BLOCK        12    /* basic block size in bits */
X#define SMALLEST_BLOCK         4    /* smallest block size in bits */
X#define LARGEST_BLOCK        24    /* allowable allocation in bits */
X#define LARGEST_NORMAL_BLOCK    16    /* largest normal allocation in bits */
X
X#define BLOCK_SIZE        (1 << BASIC_BLOCK)
X
X#define IS_DBLOCK(size)        ((size) < BLOCK_SIZE)
X
X/* number of blocks in the administrative structures */
X#define BB_PER_ADMIN    ((BLOCK_SIZE - \
X              (sizeof(long) + sizeof(int) + sizeof(char *) + \
X               sizeof(long))) / sizeof(bblock_t))
X#define DB_PER_ADMIN    ((BLOCK_SIZE - (sizeof(long) + sizeof(long))) \
X             / sizeof(dblock_t))
X
X#define CHUNK_MAGIC_BASE    0xDEA007    /* base magic number */
X#define CHUNK_MAGIC_TOP        0x976DEAD    /* top magic number */
X
X#define WHAT_BLOCK(pnt)        (((long)(pnt) / BLOCK_SIZE) * BLOCK_SIZE)
X#define CHUNK_TO_USER(pnt)    ((pnt) + pnt_below_adm)
X
X/* bb_flags values */
X#define BBLOCK_ALLOCATED    0x3F        /* block has been allocated */
X#define BBLOCK_START_USER    0x01        /* start of some user space */
X#define BBLOCK_USER        0x02        /* allocated by user space */
X#define BBLOCK_ADMIN        0x04        /* pointing to bblock admin */
X#define BBLOCK_DBLOCK        0x08        /* pointing to divided block */
X#define BBLOCK_DBLOCK_ADMIN    0x10        /* pointing to dblock admin */
X#define BBLOCK_FREE        0x20        /* block is free */
X
X/*
X * single divided-block administrative structure
X */
Xstruct dblock_st {
X  union {
X    struct {
X      unsigned short    nu_size;        /* size of contiguous area */
X      unsigned short    nu_line;        /* line where it was alloced */
X    } in_nums;
X
X    struct bblock_st    *in_bblock;        /* pointer to the bblock */
X  } db_info;
X
X  /* to reference union and struct elements as db elements */
X#define db_bblock    db_info.in_bblock    /* F */
X#define db_size        db_info.in_nums.nu_size    /* U */
X#define db_line        db_info.in_nums.nu_line    /* U */
X
X  union {
X    struct dblock_st    *pn_next;        /* next in the free list */
X    char        *pn_file;        /* .c filename where alloced */
X  } db_pnt;
X
X  /* to reference union elements as db elements */
X#define db_next        db_pnt.pn_next        /* F */
X#define db_file        db_pnt.pn_file        /* U */
X
X};
Xtypedef struct dblock_st    dblock_t;
X
X/*
X * single basic-block administrative structure
X */
Xstruct bblock_st {
X  unsigned short    bb_flags;        /* what it is */
X
X  union {
X    unsigned short    nu_bitc;        /* chunk size */
X    unsigned short    nu_line;        /* line where it was alloced */
X  } bb_num;
X
X  /* to reference union elements as bb elements */
X#define bb_bitc        bb_num.nu_bitc        /* DF */
X#define bb_line        bb_num.nu_line        /* U */
X
X  union {
X    unsigned int    in_count;        /* admin count number */
X    dblock_t        *in_dblock;        /* pointer to dblock info */
X    struct bblock_st    *in_next;        /* next in free list */
X    unsigned int    in_size;        /* size of allocation */
X  } bb_info;
X
X  /* to reference union elements as bb elements */
X#define bb_count    bb_info.in_count    /* A */
X#define    bb_dblock    bb_info.in_dblock    /* D */
X#define    bb_next        bb_info.in_next        /* F */
X#define    bb_size        bb_info.in_size        /* U */
X
X  union {
X    struct dblock_adm_st    *pn_slotp;    /* pointer to db_admin block */
X    struct bblock_adm_st    *pn_adminp;    /* pointer to bb_admin block */
X    char            *pn_mem;    /* memory associated to it */
X    char            *pn_file;    /* .c filename where alloced */
X  } bb_pnt;
X
X  /* to reference union elements as bb elements */
X#define    bb_slotp    bb_pnt.pn_slotp        /* a */
X#define    bb_adminp    bb_pnt.pn_adminp    /* A */
X#define    bb_mem        bb_pnt.pn_mem        /* DF */
X#define    bb_file        bb_pnt.pn_file        /* U */
X
X};
Xtypedef struct bblock_st    bblock_t;
X
X/*
X * collection of bblock admin structures
X */
Xstruct bblock_adm_st {
X  long            ba_magic1;        /* bottom magic number */
X  int            ba_count;        /* position in bblock array */
X  bblock_t        ba_block[BB_PER_ADMIN];    /* bblock admin info */
X  struct bblock_adm_st    *ba_next;        /* next bblock adm struct */
X  long            ba_magic2;        /* top magic number */
X};
Xtypedef struct bblock_adm_st    bblock_adm_t;
X
X/*
X * collection of dblock admin structures
X */
Xstruct dblock_adm_st {
X  long            da_magic1;        /* bottom magic number */
X  dblock_t        da_block[DB_PER_ADMIN];    /* dblock admin info */
X  long            da_magic2;        /* top magic number */
X};
Xtypedef struct dblock_adm_st    dblock_adm_t;
X
X#endif /* ! __CHUNK_LOC_H__ */
END_OF_FILE
if test 5339 -ne `wc -c <'chunk_loc.h'`; then
    echo shar: \"'chunk_loc.h'\" unpacked with wrong size!
fi
# end of 'chunk_loc.h'
fi
if test -f 'compat.c' -a "${1}" != "-c" ; then
  echo shar: Will not clobber existing file \"'compat.c'\"
else
echo shar: Extracting \"'compat.c'\" \(4789 characters\)
sed "s/^X//" >'compat.c' <<'END_OF_FILE'
X/*
X * compatibility functions for those systems who are missing them.
X *
X * Copyright 1992 by Gray Watson and the Antaire Corporation
X *
X * This file is part of the malloc-debug package.
X *
X * This library is free software; you can redistribute it and/or
X * modify it under the terms of the GNU Library General Public
X * License as published by the Free Software Foundation; either
X * version 2 of the License, or (at your option) any later version.
X *
X * This library is distributed in the hope that it will be useful,
X * but WITHOUT ANY WARRANTY; without even the implied warranty of
X * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
X * Library General Public License for more details.
X *
X * You should have received a copy of the GNU Library General Public
X * License along with this library (see COPYING-LIB); if not, write to the
X * Free Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
X *
X * The author of the program may be contacted at [e-mail]
X */
X
X/*
X * This file holds the compatibility routines necessary for the library if
X * your system does not have them.
X */
X
X#define MALLOC_DEBUG_DISABLE
X
X#include "malloc.h"
X#include "malloc_loc.h"
X
X#include "compat.h"
X#include "conf.h"
X
X#if INCLUDE_RCS_IDS
XLOCAL    char    *rcs_id =
X  "$Id: compat.c,v 1.8 1993/04/05 01:28:54 gray Exp $";
X#endif
X
X#if HAVE_MEMCPY == 0 && HAVE_BCOPY == 0
X/*
X * copy LEN characters from FROM to TO
X */
XEXPORT    char    *memcpy(char * to, const char * from, int len)
X{
X  char    *hold = to;
X
X  for (; len > 0; len--, to++, from++)
X    *to = *from;
X
X  return hold;
X}
X#endif /* HAVE_MEMCPY == 0 && HAVE_BCOPY == 0 */
X
X#if HAVE_MEMCMP == 0 && HAVE_BCMP == 0
X/*
X * compare LEN characters, return -1,0,1 if STR1 is <,==,> STR2
X */
XEXPORT    int    memcmp(const char * str1, const char * str2, int len)
X{
X  for (; len > 0; len--, str1++, str2++)
X    if (*str1 != *str2)
X      return *str1 - *str2;
X
X  return 0;
X}
X#endif /* HAVE_MEMCMP == 0 && HAVE_BCMP == 0 */
X
X#if HAVE_MEMSET == 0
X/*
X * set LEN characters in STR to character CH
X */
XEXPORT    char    *memset(char * str, int ch, int len)
X{
X  char    *hold = str;
X
X  for (; len > 0; len--, str++)
X    *str = (char)ch;
X
X  return hold;
X}
X#endif /* HAVE_MEMSET == 0 */
X
X#if HAVE_INDEX == 0
X/*
X * find CH in STR by searching backwards through the string
X */
XEXPORT    char    *index(const char * str, int ch)
X{
X  for (; *str != NULLC; str++)
X    if (*str == (char)ch)
X      return str;
X
X  return NULL;
X}
X#endif /* HAVE_INDEX == 0 */
X
X#if HAVE_RINDEX == 0
X/*
X * find CH in STR by searching backwards through the string
X */
XEXPORT    char    *rindex(const char * str, int ch)
X{
X  char    *pnt = NULL;
X
X  for (; *str != NULLC; str++)
X    if (*str == (char)ch)
X      pnt = str;
X
X  return pnt;
X}
X#endif /* HAVE_RINDEX == 0 */
X
X#if HAVE_STRCAT == 0
X/*
X * concatenate STR2 onto the end of STR1
X */
XEXPORT    char    *strcat(char * str1, const char * str2)
X{
X  char    *hold = str1;
X
X  for (; *str1 != NULLC; str1++);
X
X  while (*str2 != NULLC)
X    *str1++ = *str2++;
X  *str1 = NULLC;
X
X  return hold;
X}
X#endif /* HAVE_STRCAT == 0 */
X
X#if HAVE_STRCMP == 0
X/*
X * returns -1,0,1 on whether STR1 is <,==,> STR2
X */
XEXPORT    int    strcmp(const char * str1, const char * str2)
X{
X  for (; *str1 != NULLC && *str1 == *str2; str1++, str2++);
X  return *str1 - *str2;
X}
X#endif /* HAVE_STRCMP == 0 */
X
X#if HAVE_STRLEN == 0
X/*
X * return the length in characters of STR
X */
XEXPORT    int    strlen(const char * str)
X{
X  int    len;
X
X  for (len = 0; *str != NULLC; str++, len++);
X
X  return len;
X}
X#endif /* HAVE_STRLEN == 0 */
X
X#if HAVE_STRTOK == 0
X/*
X * get the next token from STR (pass in NULL on the 2nd, 3rd, etc. calls),
X * tokens are a list of characters deliminated by a character from DELIM.
X * writes null into STR to end token.
X */
XEXPORT    char    *strtok(char * str, char * delim)
X{
X  static char    *last_str = "";
X  char        *start, *delimp;
X
X  /* no new strings to search? */
X  if (str != NULL)
X    last_str = str;
X  else
X    /* have we reached end of old one? */
X    if (*last_str == NULLC)
X      return NULL;
X
X  /* parse through starting token deliminators */
X  for (; *last_str != NULLC; last_str++) {
X    for (delimp = delim; *delimp != NULLC; delimp++)
X      if (*last_str == *delimp)
X    break;
X
X    /* is the character NOT in the delim list? */
X    if (*delimp == NULLC)
X      break;
X  }
X
X  /* did we reach the end? */
X  if (*last_str == NULLC)
X    return NULL;
X
X  /* now start parsing through the string, could be NULLC already */
X  for (start = last_str; *last_str != NULLC; last_str++)
X    for (delimp = delim; *delimp != NULLC; delimp++)
X      if (*last_str == *delimp) {
X    /* punch NULL and point last_str past it */
X    *last_str++ = NULLC;
X    return start;
X      }
X
X  /* reached the end of the string */
X  return start;
X}
X#endif /* HAVE_STRTOK == 0 */
END_OF_FILE
if test 4789 -ne `wc -c <'compat.c'`; then
    echo shar: \"'compat.c'\" unpacked with wrong size!
fi
# end of 'compat.c'
fi
if test -f 'compat.h' -a "${1}" != "-c" ; then
  echo shar: Will not clobber existing file \"'compat.h'\"
else
echo shar: Extracting \"'compat.h'\" \(2476 characters\)
sed "s/^X//" >'compat.h' <<'END_OF_FILE'
X/*
X * header file for compatibility functions.
X *
X * Copyright 1992 by Gray Watson and the Antaire Corporation
X *
X * This file is part of the malloc-debug package.
X *
X * This library is free software; you can redistribute it and/or
X * modify it under the terms of the GNU Library General Public
X * License as published by the Free Software Foundation; either
X * version 2 of the License, or (at your option) any later version.
X *
X * This library is distributed in the hope that it will be useful,
X * but WITHOUT ANY WARRANTY; without even the implied warranty of
X * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
X * Library General Public License for more details.
X *
X * You should have received a copy of the GNU Library General Public
X * License along with this library (see COPYING-LIB); if not, write to the
X * Free Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
X *
X * The author of the program may be contacted at [e-mail]
X *
X * $Id: compat.h,v 1.7 1993/04/05 01:28:57 gray Exp $
X */
X
X#ifndef __COMPAT_H__
X#define __COMPAT_H__
X
X#include "malloc.h"            /* for IMPORT ... */
X
X/*<<<<<<<<<<  The below prototypes are auto-generated by fillproto */
X
X/*
X * copy LEN characters from FROM to TO
X */
X#if __GNUC__ < 2
XIMPORT    char    *memcpy(char * to, const char * from, int len);
X#endif
X
X/*
X * compare LEN characters, return -1,0,1 if STR1 is <,==,> STR2
X */
X#if __GNUC__ < 2
XIMPORT    int    memcmp(const char * str1, const char * str2, int len);
X#endif
X
X/*
X * set LEN characters in STR to character CH
X */
XIMPORT    char    *memset(char * str, int ch, int len);
X
X/*
X * find CH in STR by searching backwards through the string
X */
XIMPORT    char    *index(const char * str, int ch);
X
X/*
X * find CH in STR by searching backwards through the string
X */
XIMPORT    char    *rindex(const char * str, int ch);
X
X/*
X * concatenate STR2 onto the end of STR1
X */
XIMPORT    char    *strcat(char * str1, const char * str2);
X
X/*
X * returns -1,0,1 on whether STR1 is <,==,> STR2
X */
XIMPORT    int    strcmp(const char * str1, const char * str2);
X
X/*
X * return the length in characters of STR
X */
XIMPORT    int    strlen(const char * str);
X
X/*
X * get the next token from STR (pass in NULL on the 2nd, 3rd, etc. calls),
X * tokens are a list of characters deliminated by a character from DELIM.
X * writes null into STR to end token.
X */
XIMPORT    char    *strtok(char * str, char * delim);
X
X/*<<<<<<<<<<   This is end of the auto-generated output from fillproto. */
X
X#endif /* ! __COMPAT_H__ */
END_OF_FILE
if test 2476 -ne `wc -c <'compat.h'`; then
    echo shar: \"'compat.h'\" unpacked with wrong size!
fi
# end of 'compat.h'
fi
if test -f 'conf.h.in' -a "${1}" != "-c" ; then
  echo shar: Will not clobber existing file \"'conf.h.in'\"
else
echo shar: Extracting \"'conf.h.in'\" \(4016 characters\)
sed "s/^X//" >'conf.h.in' <<'END_OF_FILE'
X/*
X * machine configuration flags
X *
X * Copyright 1992 by Gray Watson and the Antaire Corporation
X *
X * This file is part of the malloc-debug package.
X *
X * This library is free software; you can redistribute it and/or
X * modify it under the terms of the GNU Library General Public
X * License as published by the Free Software Foundation; either
X * version 2 of the License, or (at your option) any later version.
X *
X * This library is distributed in the hope that it will be useful,
X * but WITHOUT ANY WARRANTY; without even the implied warranty of
X * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
X * Library General Public License for more details.
X *
X * You should have received a copy of the GNU Library General Public
X * License along with this library (see COPYING-LIB); if not, write to the
X * Free Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
X *
X * The author of the program may be contacted at [e-mail]
X *
X * $Id: conf.h.in,v 1.9 1993/04/06 04:24:30 gray Exp $
X */
X
X/*
X ************************************************************************
X * USER SETTINGS:
X ************************************************************************
X */
X
X/*
X * include the RCS ids in the .c files and the installed library
X */
X#define INCLUDE_RCS_IDS 1
X
X/*
X * should we allow zero length allocations or should be registered as errors.
X * WARNING: this has not been tested although some code does exist for it.
X */
X#define ALLOW_ALLOC_ZERO_SIZE 0
X
X/*
X * should we allow realloc of a NULL pointer.  this is useful when you are
X * extending an array in a loop and do not want to allocate it specially the
X * first time.
X */
X#define ALLOW_REALLOC_NULL 1
X
X/*
X ************************************************************************
X * SPECIAL DEFINES:
X ************************************************************************
X */
X
X/*
X * (char *)sbrk(int incr) is the main system memory allocation routine.  this
X * extends the program's data space by INCR bytes.
X */
X#define HAVE_SBRK 0
X
X/*
X * does your heap grow up?  Hopefully it does because there is not too much
X * support for growing-down heaps because I do not have a system to test it on.
X */
X#define HEAP_GROWS_UP 1
X
X/*
X * the alignment value of all allocations in number of bits (i.e. 2 ^ X) for
X * fence-post checking.  it needs to be a base 2 number and 3 (i.e. 2 ^ 3 == 8)
X * should work.  2 bits may also work on i386/i486 systems (for instance) but
X * some RISC boxes (sparc for instance) require certain memory to be base 8
X * (stack frames, code, etc.).
X *
X * NOTE: larger the number the more memory will be wasted when fence-checking
X * NOTE: this is not necessarily the smallest possible allocated memory chunk
X */
X#define ALLOCATION_ALIGNMENT_IN_BITS 3
X
X/*
X ************************************************************************
X * LIBRARY DEFINES:
X ************************************************************************
X */
X
X/*
X * the Malloc-Debug library provides its own versions of the following
X * functions,  or knows how to work around their absence.
X */
X#define HAVE_BCMP 0
X#define HAVE_BCOPY 0
X
X#define HAVE_MEMCMP 0
X#define HAVE_MEMCPY 0
X#define HAVE_MEMSET 0
X
X#define HAVE_INDEX 0
X#define HAVE_RINDEX 0
X
X#define HAVE_STRCAT 0
X#define HAVE_STRCMP 0
X#define HAVE_STRLEN 0
X#define HAVE_STRTOK 0
X
X/*
X * the below functions are here to provide function argument checking only.
X */
X#define HAVE_BZERO 0
X
X#define HAVE_MEMCCPY 0
X#define HAVE_MEMCHR 0
X
X#define HAVE_STRCHR 0
X#define HAVE_STRRCHR 0
X#define HAVE_STRCPY 0
X#define HAVE_STRNCPY 0
X#define HAVE_STRCASECMP 0
X#define HAVE_STRNCASECMP 0
X#define HAVE_STRSPN 0
X#define HAVE_STRCSPN 0
X#define HAVE_STRNCAT 0
X#define HAVE_STRNCMP 0
X#define HAVE_STRPBRK 0
X#define HAVE_STRSTR 0
X
X/*
X * some defines to standardize memory functions
X */
X#if HAVE_BCMP == 0
X#define bcmp(s1, s2, len)    (void)memcmp((char *)(s1), (char *)(s2), (len))
X#endif
X
X#if HAVE_BCOPY == 0
X#define bcopy(from, to, len)    (void)memcpy((char *)(to), (char *)(from), len)
X#endif
END_OF_FILE
if test 4016 -ne `wc -c <'conf.h.in'`; then
    echo shar: \"'conf.h.in'\" unpacked with wrong size!
fi
# end of 'conf.h.in'
fi
if test -f 'malloc.texi' -a "${1}" != "-c" ; then
  echo shar: Will not clobber existing file \"'malloc.texi'\"
else
echo shar: Extracting \"'malloc.texi'\" \(41525 characters\)
sed "s/^X//" >'malloc.texi' <<'END_OF_FILE'
X\input texinfo @c -*-texinfo-*-
X@c %**start of header
X@setfilename malloc.info
X@settitle Malloc Tutorial
X@c %**end of header
X
X@c ================================================================
X@c This file has the new style title page commands.
X@c Also, it uses `@@include' files instead of `@@input' files.
X
X@c Run using special version of `texinfo.tex'.
X
X@c Also, run `makeinfo' rather than `texinfo-format-buffer'.
X@c ================================================================
X
X@c ================================================================
X@c $Id: malloc.texi,v 1.12 1993/04/06 04:24:36 gray Exp $
X@c ================================================================
X
X@ifinfo
XThis file is an introduction to the Malloc library which handles general
Xmemory heap management.
X
XCopyright @copyright{} 1992 by Gray Watson and the Antaire Corporation.
X
XPermission is granted to make and distribute verbatim copies of this
Xmanual provided the copyright notice and this permission notice are
Xpreserved on all copies.
X
X@ignore
XPermission is granted to process this file through TeX and print the
Xresults, provided the printed document carries a copying permission
Xnotice identical to this one except for the removal of this paragraph
X(this paragraph not being relevant to the printed manual).
X
X@end ignore
XPermission is granted to copy and distribute modified versions of this
Xmanual under the conditions for verbatim copying, provided also that the
Xsection entitled ``Copying'' are included exactly as in the original,
Xand provided that the entire resulting derived work is distributed under
Xthe terms of a permission notice identical to this one.
X
XPermission is granted to copy and distribute translations of this manual
Xinto another language, under the above conditions for modified versions,
Xexcept that the section entitled ``Copying'' may be included in a
Xtranslation approved by the author instead of in the original English.
X@end ifinfo
X
X@titlepage
X@title Malloc Debug Library
X@author Gray Watson @samp{<gray.watson@@antaire.com>}
X
X@page
XCopyright @copyright{} 1992 by Gray Watson and the Antaire Corporation.
X
XPublished by Gray Watson @samp{<gray.watson@@antaire.com>}
X
XPermission is granted to make and distribute verbatim copies of this
Xmanual provided the copyright notice and this permission notice are
Xpreserved on all copies.
X
XPermission is granted to copy and distribute modified versions of this
Xmanual under the conditions for verbatim copying, provided also that the
Xsection entitled ``Copying'' are included exactly as in the original,
Xand provided that the entire resulting derived work is distributed under
Xthe terms of a permission notice identical to this one.
X
XPermission is granted to copy and distribute translations of this manual
Xinto another language, under the above conditions for modified versions,
Xexcept that the section entitled ``Copying'' may be included in a
Xtranslation approved by the author instead of in the original English.
X@end titlepage
X
X@node Top, Copying, (dir), (dir)
X@top Malloc Debug Library
X
XThis file documents the general-usage and the inner-workings of the
Xmemory allocation or @dfn{malloc} library it accompanies.
X
XThis malloc library has been designed as a drop in replacement for the
Xsystem's malloc, realloc, calloc, free and other memory management
Xroutines.  For more information about their capabilities, do a @code{man
X3 malloc} to read the system's manual pages.
X
XWhat is unique about this library is that it contains a number of
Xpowerful debugging facilities including very comprehensive heap testing
Xand excellent run-time debugging information.  We have found these
Xcapabilities to be superb development tools.
X
XI can be reached at @samp{<gray.watson@@antaire.com>} with any questions
Xor general comments.
X
XGray Watson, Antaire Corporation.
X
X@menu
X* Copying::             Library copying conditions.
X* Allocation Basics::   Basic description of terms and functions.
X* Features::            Description of the benefits of the library.
X* Usage::               How to run programs with the library.
X* Code::                Information on the source and general concerns.
X* Plugs::               A couple soapbox comments.
X@end menu
X
X@node Copying, Allocation Basics, Top, Top
X@chapter Library Copying Conditions.
X
XThis package is covered by the GNU Library Public License.  See the file
X@file{COPYING-LIB} for details.  If you would like to do something with
Xthis package that you feel is reasonable but prohibited by the license,
Xplease contact me to see if we can work it out.
X
X@emph{NOTICE}: this is not the GNU Public License but the @emph{library}
Xpublic license.  This license allows you to do more with the library
Xthan the standard public license distributed with most GNU software.
XPlease read @file{COPYING-LIB} or contact me for more information.
X
XThe rest of this section contains some messages from the Free Software
XFoundation.  If you find this stuff offensive or annoying, remember that
Xyou probably did not spend any money to get this library so feel free to
Xheave it into the bit bucket.
X
XThe licenses for most software are designed to take away your freedom to
Xshare and change it.  By contrast, the GNU General Public Licenses are
Xintended to guarantee your freedom to share and change free software--to
Xmake sure the software is free for all its users.
X
XThis license, the Library General Public License, applies to some
Xspecially designated Free Software Foundation software, and to any other
Xlibraries whose authors decide to use it.  You can use it for your
Xlibraries, too.
X
XWhen we speak of free software, we are referring to freedom, not price.
XOur General Public Licenses are designed to make sure that you have the
Xfreedom to distribute copies of free software (and charge for this
Xservice if you wish), that you receive source code or can get it if you
Xwant it, that you can change the software or use pieces of it in new
Xfree programs; and that you know you can do these things.
X
XTo protect your rights, we need to make restrictions that forbid anyone
Xto deny you these rights or to ask you to surrender the rights.  These
Xrestrictions translate to certain responsibilities for you if you
Xdistribute copies of the library, or if you modify it.
X
XFor example, if you distribute copies of the library, whether gratis or
Xfor a fee, you must give the recipients all the rights that we gave you.
XYou must make sure that they, too, receive or can get the source code.
XIf you link a program with the library, you must provide complete object
Xfiles to the recipients so that they can relink them with the library,
Xafter making changes to the library and recompiling it.  And you must
Xshow them these terms so they know their rights.
X
XOur method of protecting your rights has two steps: (1) copyright the
Xlibrary, and (2) offer you this license which gives you legal permission
Xto copy, distribute and/or modify the library.
X
XAlso, for each distributor's protection, we want to make certain that
Xeveryone understands that there is no warranty for this free library.
XIf the library is modified by someone else and passed on, we want its
Xrecipients to know that what they have is not the original version, so
Xthat any problems introduced by others will not reflect on the original
Xauthors' reputations.
X
X@node Allocation Basics, Features, Copying, Top
X@chapter Basic Description of Terms and Functions.
X
XThis section provides a basic definition of terms used throughout the
Xmanual as well as a brief overview of the basic malloc functions and
Xexamples of their use.  It is quite unnecessary for you to read this
Xsection if you are familiar with using the heap allocation functions.
X
X@menu
X* Basic definitions::   For defining general terms and concepts.
X* Malloc functions::    Functionality supported by all malloc libs.
X@end menu
X
X@node Basic definitions, Malloc functions,  , Allocation Basics
X@section For Defining General Terms and Concepts.
X
XAny program can be divided into 2 logical parts: text and data.  Text is
Xthe actual program code in machine-readable format and data is the
Xinformation that the text operates on when it is executing.  The data,
Xin turn, can be divided into 3 logical parts according to where it is
Xstored: @dfn{static}, @dfn{stack}, and @dfn{heap}.
X
XStatic data is the information whose storage space is compiled into the
Xprogram.
X@example
X        /* global variables are allocated as static data */
X        int numbers[10];
X
X        main()
X        @{
X           @dots{}
X        @}
X@end example
XStack data is data allocated at run-time to hold information used inside
Xof functions.  This data is managed by the system in the space called
Xstack space.
X
X@example
X        void foo()
X        @{
X           /* this local variable is allocated on the stack */
X           float total;
X
X           @dots{}
X        @}
X@end example
XHeap data is also allocated at run-time and provides a programmer with
Xdynamic memory capabilities.
X
X@example
X        main()
X        @{
X           char * string;
X           @dots{}
X
X           /* allocate a string of 10 bytes */
X           string = (char *)malloc(10);
X           @dots{}
X           /* de-allocate the string now that I'm done with it */
X           (void)free(string);
X
X           @dots{}
X        @}
X@end example
XIt is the heap data that is managed by this library.
X
XAlthough the above is an example of how to use the malloc and free
Xcommands, it is not a good example of why using the heap for run-time
Xstorage is useful.
X
XConsider this: You write a program that reads a file into memory,
Xprocesses it, and displays results.  You would like to handle files with
Xarbitrary size (from 10 bytes to 1.2 megabytes and more).  One problem,
Xhowever, is that the entire file must be in memory at one time to do the
Xcalculations.  You don't want to have to allocate 1.2 megabytes when you
Xmight only be reading in a 10 byte file because it is wasteful of system
Xresources.  Also, you are worried that your program might have to handle
Xfiles of more than 1.2 megabytes.
X
XA solution: first checkout the file's size and then, using the
Xheap-allocation routines, get enough storage to read the entire file
Xinto memory.  The program will only be using the system resources
Xnecessary for the job and you will be guaranteed that your program can
Xhandle any sized file.
X
X@node Malloc functions,  , Basic definitions, Allocation Basics
X@section Functionality Supported by all Malloc Libraries.
X
XAll malloc libraries support 4 basic memory allocation commands.  These
Xinclude @dfn{malloc}, @dfn{calloc}, @dfn{realloc}, and @dfn{free}.
X
X@table @samp
X@item malloc
XUsage: @code{pnt = (type *)malloc(unsigned int size);}
X
XThe malloc routine is the basic memory allocation routine.  It allocates
Xan area of size bytes.  It will return a pointer to the space requested.
X
X@item calloc
XUsage: @code{pnt = (type *)calloc(unsigned int number, unsigned int
Xsize);}
X
XThe calloc routine allocates a certain number of items, each of size
Xbytes, and returns a pointer to the space.  It is appropriate to pass in
Xa @code{sizeof(type)} value as the size argument.
X
XAlso, calloc nulls the space that it returns, assuring that the memory
Xis all zeros.
X
X@item realloc
XUsage: @code{new_pnt = (type *)realloc(void * old_pnt, unsigned
Xint new_size);}
X
XThe realloc function expands or shrinks the memory allocation in old_pnt
Xto new_size number of bytes.  Realloc copies the information in old_pnt
Xinto the new_pnt space up to new_size bytes or until it copies all of
Xthe information from old_pnt.
X
X@item free
XUsage: @code{(void)free(void * pnt);}
X
XThe free routine releases an allocation returned by malloc, calloc, or
Xrealloc back to the heap.  This allows other parts of the program to
Xre-use memory that is not needed anymore.  It also guarantees that the
Xprocess does not grow too big and swallow a large portion of the system
Xresources.
X
X@end table
X
X@emph{NOTE}: the returned address from the memory
Xallocation/reallocation functions should @emph{always} be cast to the
Xappropriate pointer type for the variable being assigned.
X
X@emph{WARNING}: there is a quite common myth that all of the space that
Xis returned by malloc libraries has already been cleared.  @emph{Only}
Xthe calloc routine will zero the memory space it returns.
X
X@node Features, Usage, Allocation Basics, Top
X@chapter Description of the Benefits of the Library.
X
X@menu
X* Overview::                    General debugging concepts.
X* Environment variables::       The variable names and their features.
X* malloc_dbg program::          Env variable setting utility.
X* RC file::                     Format of the run-time configuration file.
X* Debug tokens::                Description of the debugging token flags.
X* Argument checking::           Special checking of function arguments.
X@end menu
X
X@node Overview, Environment variables,  , Features
X@section General Debugging Concepts.
X
XThe features of this library are controlled by a number of environmental
Xvariables.  They enable the memory debugging features at runtime to help
Xlocate problems, chart memory leaks, provide basic bounds checking, log
Xstatistics, etc.. @xref{Environment variables}.
X
XThe debugging features that are available can be broken down into a
Xcouple basic classifications:
X
X@table @samp
X@item file and line number information
XOne of the nice things about a good debugger is its ability to provide
Xthe file and line number of an offending piece of code.  This library
Xattempts to give this functionality with the help of @dfn{cpp}, the C
Xpreprocessor.  If the file @file{malloc.h} is included, the library can
Xprovide file and line information for the warning messages and errors it
Xgenerates.
X
X@item fence-post (i.e. bounds) checking
X@dfn{Fence-post} memory is the area immediately above or below memory
Xallocations.  I have found it all to easy to write code that accesses
Xabove or below an allocation (especially when dealing with arrays or
Xstrings).  The library can write special values in the areas around
Xevery allocation so it will notice when these areas have been
Xoverwritten.
X
X@emph{NOTE}: The library cannot notice when the program reads from these
Xareas, only when it writes values.  Also, fence-post checking will
Xincrease the amount of memory the program allocates.
X
X@item heap-constancy verification
XThe administration of the library is reasonably complex.  If any of the
Xheap-maintenance information is corrupted, the program will either crash
Xor give unpredictable results.
X
XBy enabling heap-consistency checking, the library will run through its
Xadministrative structures to make sure all is in order.  This will mean
Xthat problems will be caught faster and diagnosed better.
X
XThe drawback of this is, of course, that the library often takes quite a
Xlong time to do this.  It is suitable to enable this only during
Xdevelopment and debugging sessions.
X
X@emph{NOTE}: the heap checking routines cannot guarantee that the tests
Xwill not cause a segmentation-fault if the heap administration
Xstructures are properly (or improperly if you will) overwritten.  In
Xother words, they will verify that everything is okay but may not inform
Xthe user of problems in a graceful manner.
X
X@item logging statistics
XOne of the initial reasons why I personally wanted malloc-debug
Xcapabilities is to track my programs' memory usage; specifically to
Xlocate memory @dfn{leaks} which are places where allocated memory is
Xnever getting freed.
X
XThe library has a number of logging capabilities that can track run-time
Xmemory usage, administrative actions, final program statistics, as well
Xas un-freed memory pointers.  This information is also good at providing
Xmore general debugging feedback.
X
X@item examining unfreed memory
XAnother common problem with programs is that they free a memory pointer
Xbut then use go on to use it again by mistake.  This can lead to
Xmysterious crashes and unexplained problems.
X
XTo combat this, the library can write special values into a block of
Xmemory after it has been freed.  This serves two purposes: it will make
Xsure that the program will get garbage data if it trying to access the
Xarea again, and it will allow the library to verify the area later for
Xsigns of overwriting.
X@end table
X
XIf any of the above debugging features detect an error, the library will
Xtry to recover.  If logging is enabled then an error will be logged with
Xas much information as possible.
X
XThe error messages that the library displays are designed to give the
Xmost information for developers.  If the error message is not
Xunderstood, then it is most likely just trying to indicate that a part
Xof the heap has been corrupted.  The bug is most likely near the last
Xcall made to the library so reviewing the code around this area is
Xrecommended.
X
XThe library can be configured to quit immediately when an error is
Xdetected and to dump a core file or memory-image.  This can be examined
Xwith a debugger to determine the source of the problem.
X
XWhen running our programs in a debugger such as gdb (the
X@emph{excellent} GNU debugger), I always put a break-point in
X@code{_malloc_perror()} which is the internal error routine for the
Xlibrary.  The program will then hit the break-point as soon as a memory
Xproblem is detected.
X
XOther malloc-debug libraries also support the ability to dump core and
Xthen continue running.  I decided not to support this once it was
Xdetermined that some versions of @code{fork} make calls to malloc which
Xwould cause the library to go recursive.
X
X@emph{NOTE}: do not be surprised if the library catches problems with
Xyour system's library routines.  It took me four hours once to finally
Xcome to the conclusion that the localtime call, included in SunOS
Xrelease 4.1, was overwriting one of its fence-post markers.
X
X@node Environment variables, malloc_dbg program, Overview, Features
X@section Environment Variables - Their Names and Features.
X
X@dfn{Environment variables} are variables that are part of the user's
Xworking environment and are shared by all the programs.  The below
Xvariables are used by the malloc library to enable or disable the memory
Xdebugging features, at runtime.
X
XThey can be set either by hand or with the help of the malloc_dbg
Xprogram.  @xref{malloc_dbg program}.
X
XTo set them by hand, C shell (or tcsh) users need to invoke:
X
X@example
X        setenv variable value;
X@end example
XBourne shell (or bash, ksh) users should use:
X
X@example
X        variable=value;
X        export variable;
X@end example
X@table @samp
X@item MALLOC_DEBUG
XThis env variable should be set to a value in hexadecimal which
Xcorresponds to a set of functionality tokens.  @xref{Debug tokens}.  For
Xinstance, if the user wanted to enabled logging of memory transactions
X(value @samp{0x008}) and wanted to check fence-post memory (value
X@samp{0x400}) then @samp{MALLOC_DEBUG} should be set to @samp{0x408}.
X
XDon't worry about remembering all the hex values of the tokens, the
Xmalloc_dbg program automates the setting of this variable especially.
X
X@item MALLOC_LOGFILE
XSet this variable to a filename so that if @samp{MALLOC_DEBUG} has
Xlogging enabled, the library can log transactions, administration
Xinformation, and/or errors to the file so memory problems and usage can
Xbe tracked.
X
X@item MALLOC_ADDRESS
XWhen this env variable is set to a hex address (taken from the malloc
Xlog-file for instance) malloc will abort when it finds itself either
Xallocating or freeing that address.
X
XThe address can also have an @samp{:number} argument.  For instance, if
Xit was set it to @samp{0x3e45:10}, the library will kill itself the 10th
Xtime it sees address @samp{0x3e45}.
X
XThis makes it easier to track down specific addresses not being freed.
X
X@item MALLOC_INTERVAL
XBy setting this env variable to a number X, malloc will only check the
Xheap every X times.  This means a number of @samp{MALLOC_DEBUG} features
Xcan be enabled while still running the program within a finite amount of
Xtime.
X
XI have found that a setting of @samp{100} works well with reasonably
Xmemory intensive programs.  This of course means that the library will
Xnot catch errors exactly when they happen but possibly 100 library calls
Xlater.
X
X@item MALLOC_START
XSet this env variable to a number X and malloc will begin checking the
Xheap after X times.  This means the intensive debugging can be started
Xafter a certain point in a program.
X
X@samp{MALLOC_START} also has the format file:line.  For instance, if it
Xis set to @samp{malloc_t.c:126} malloc will start checking the heap
Xafter it sees a malloc call from the @file{malloc_t.c} file, line number
X126.  If line number is 0 then malloc will start checking the heap after
Xit sees a call from anywhere in the @file{malloc_t.c} file.
X
XThis allows the intensive debugging to be started after a certain
Xroutine or file has been reached in the program.
X@end table
X
X@node malloc_dbg program, RC file, Environment variables, Features
X@section Env Variable Setting Utility.
X
XThe malloc_dbg program is designed to assist in the setting of the
Xenvironmental variables, especially @samp{MALLOC_DEBUG}.
X@xref{Environment variables}.  It is designed to print the shell
Xcommands necessary to make the appropriate changes to the environment.
XUnfortunately, it cannot make the changes on its own so the output from
Xmalloc_dbg should be sent through the @code{eval} shell command which
Xwill do the commands.
X
XWith shells that have aliasing or macro capabilities: csh, tcsh, bash,
Xksh, etc., setting up an alias to malloc_dbg to do the eval call is
Xrecommended.  csh/tcsh users (for example) should put the following in
Xtheir @file{.cshrc} file:
X
X@example
X        alias malloc 'eval `malloc_dbg \!*`'
X@end example
XThis allows the user to execute @code{malloc args}.
X
XThe most basic usage for the program is @code{malloc_dbg [-b] tag}.  The
X-b flag is for generating Bourne-shell type commands (C-shell type are
Xthe default).  The tag argument should match a line from the user's
Xrun-time configuration file.  @xref{RC file}.
X
XHere is a detailed list of the flags that can passed to malloc_dbg:
X
X@table @samp
X@item -a address
XSet the @samp{MALLOC_ADDRESS} variable with the string address (or
Xalternatively address:number).
X
X@item -b
XOutput Bourne-shell type commands.  (C-shell type output is the
Xdefault).
X
X@item -c
XClear/unset all of the variables not specified with other arguments.
X
X@emph{NOTE}: clear will never unset the @samp{MALLOC_DEBUG} variable.
XUse @samp{-d 0} or a tag to @samp{none} to achieve this.
X
X@item -d bitmask
XSet the MALLOC_DEBUG to the bitmask value which should be in hex.  This
Xis overridden (and unnecessary) if a tag is specified.
X
X@item -e errno
XPrint the malloc error string that corresponds to errno.
X
X@item -f filename
XUse this configuration file instead of the RC file
X@file{$HOME/.mallocrc}.
X
X@item -i number
XSet the @samp{MALLOC_INTERVAL} env variable to number.
X
X@item -l filename
XSet the @samp{MALLOC_LOGFILE} env variable to filename.
X
X@item -s number
XSet the @samp{MALLOC_START} env variable to number (alternatively
Xfile:line).
X@end table
X
XIf no arguments are specified, malloc_dbg dumps out the current settings
Xthat you have for the malloc environmental variables.  For example:
X
X@example
X        MALLOC_DEBUG == '0x6417' (debug1)
X        MALLOC_ADDRESS == '0'
X        MALLOC_INTERVAL not set
X        MALLOC_LOGFILE == 'malloc'
X        MALLOC_START not set
X@end example
X
X@node RC file, Debug tokens, malloc_dbg program, Features
X@section Format of the Run-Time Configuration File.
X
XThe name of default @dfn{RC file} (or run-time configuration file) is
X@file{$HOME/.mallocrc}.  The @samp{$HOME} environmental variable should
Xbe set by the system to point to your home-directory.
X
XThe rc file file should contain lines in the general form of:
X
X        @code{tag token1, token2, ...}
X
Xtag is to be matched with the tag argument passed to the malloc_dbg
Xprogram, token1, token2, ... are debug capability tokens.
X@xref{malloc_dbg program} and @ref{Debug tokens}.
X
XA line can be finished with a '\' meaning it continues onto the next
Xline.  Lines beginning with '#' are treated as comments and are ignored
Xalong with empty lines.
X
XI have the below contents in my @file{.mallocrc} file:
X
X@example
X#
X# Malloc run-time configuration file for our malloc-debug library
X#
X
X# no debugging
Xnone    none
X
X# basic debugging
Xdebug1    log-stats, log-non-free, log-perror, log-bad-pnt, check-fence
X
X# more logging and some heap checking
Xdebug2    log-stats, log-non-free, log-perror, log-trans, log-bad-pnt, \
X    check-fence, check-heap, check-lists, error-abort
X
X# good utilities
Xdebug3    log-stats, log-non-free, log-perror, log-trans, log-bad-pnt, \
X    log-admin, check-fence, check-heap, check-lists, realloc-copy, \
X    free-blank, error-abort
X
X@dots{}
X@end example
XWith the above file, when I say @code{eval `malloc_dbg debug1`}, I
Xenable the logging of statistics, the logging of non-freed memory,
Xlogging of errors, logging of bad pointer information, and the checking
Xof fence-post memory areas.
X
XWhen I say @code{eval `malloc_dbg none`}, all memory debugging features
Xare disabled.
X
X@node Debug tokens, Argument Checking, RC file, Features
X@section Description of the Debugging Token Flags.
X
XThe below tokens and their corresponding descriptions are for the
Xsetting of the @samp{MALLOC_DEBUG} environmental variable
X@xref{Environment variables}.  They should be specified in the user's
X@file{.mallocrc} file @xref{RC file}.
X
X@table @samp
X@item none
Xno debugging functionality
X
X@item log-stats
Xlog general statistics when malloc_shutdown is called
X
X@item log-non-free
Xlog non-freed memory pointers when malloc_shutdown is called
X
X@item log-perror
Xlog internal error-messages
X
X@item log-trans
Xlog general memory transactions
X
X@item log-bad-pnt
Xlog information about bad-pointers
X
X@item log-admin
Xlog full administrative information
X
X@item log-blocks
Xlog detailed block information when malloc_heap_map is called
X
X@item log-unknown
Xlike log-non-free but logs unknown non-freed memory pointers
X
X@item check-fence
Xcheck fence-post memory areas
X
X@item check-heap
Xverify heap administrative structure
X
X@item check-lists
Xexamine internal heap linked-lists
X
X@item check-dblock
Xdo detailed checking on small allocations
X
X@item check-dblock-fence
Xcheck the fence-post areas of small allocations
X
X@item check-free
Xcheck to see if free space has been overwritten
X
X@item check-funcs
Xcheck the arguments of some functions (mostly string operations) looking
Xfor bad pointers
X
X@item realloc-copy
Xalways copy data to a new pointer when realloc
X
X@item free-blank
Xwrite special values (non-0) into space when it is freed
X
X@item error-abort
Xabort the program (and dump core) on errors
X
X@item alloc-blank
Xwrite special values (non-0) into space when it is alloced
X
X@item heap-check-map
Xlog a heap-map to the logfile every time the heap is checked
X
X@item print-perror
Xlog any errors and messages to the screen via standard-error
X@end table
X
X@node Argument Checking,  , Debug tokens, Features
X@section Check Certain Function Arguments.
X
XOne potential problem with the library and its multitude of checks and
Xdiagnoses is that they only get performed when a malloc function is
Xcalled.  One solution this is to include @file{malloc.h} and compile
Xyour source code with the @code{MALLOC_FUNC_CHECK} flag defined and
Xenable the @code{check-funcs} token @xref{Debug tokens}.
X
X@example
X        gcc -DMALLOC_FUNC_CHECK file.c
X@end example
XOnce you have compiled your source with FUNC_CHECK enabled, you will
Xhave to recompile with it off to disconnect the library @xref{Disabling
Xthe Library}.
X
XWhen this is defined malloc will override a number of functions and will
Xinsert a routine which knowns how to check its own arguments and then
Xcall the real function.  Malloc can check such functions as bcopy,
Xindex, strcat, and strcasecmp (for the full list see the end of
X@file{malloc.h}).
X
XWhen you call strlen, for instance, malloc will make sure the string
Xargument's fence-post areas have not been overwritten, its file and line
Xnumber locations are good, etc.  With bcopy, malloc will make sure that
Xthe destination string has enough space to store the number of bytes
Xspecified.
X
XFor all of the arguments checked, if the pointer is not in the heap then
Xit is ignored since malloc does know anything about it.
X
X@emph{NOTE}: this is one of the newest parts of the library so problems
Xmay still be lurking.
X
X@node Usage, Code, Features, Top
X@chapter How to Run Programs With the Library.
X
X@menu
X* Allocation macros::           For providing file and line information.
X* Extensions::                  Additional non-standard routines.
X* Disabling the Library::       How to compile/link without the library.
X@end menu
X
X@node Allocation macros, Extensions,  , Usage
X@section For Providing File/Line Debugging Information.
X
XBy including @file{malloc.h} in your C files, your calls to calloc,
Xfree, malloc, or realloc are replaced with calls to _calloc_leap,
X_free_leap, _malloc_leap, and _realloc_leap.
X
XThese leap macros use the c-preprocessor @code{__FILE__} and
X@code{__LINE__} macros which get replaced at compilation time with the
Xcurrent file and line-number of the source code in question.  The leap
Xroutines take this information and pass it on to the library making it
Xable to produce verbose reports on memory not freed:
X
X@example
X    not freed: 0x38410 ( 22 bytes) from 'malloc_t.c:92'
X        not freed: 0x38600 ( 10232 bytes) from 'malloc_t.c:104'
X@end example
XThese lines from a log file shows that two allocations were not freed.
XOne at address 0x38410 of size 22 bytes in source file @file{malloc_t.c}
Xat line 92 and another at address 0x38600 of size 10232 bytes at line
X104 of @file{malloc_t.c}.
X
XAlong with the above leap macros, @file{malloc.h} also contains the
Xfollowing macros which I have been using for all our memory allocation
Xneeds for some time now.  They take care of all the type-casting and
Xmake the code look much cleaner (IMHO).
X
X@table @code
X@item ALLOC(type, count)
XUsage: @code{long_pnt = ALLOC(long, 30);}.  This means allocate space
Xfor 30 longs.
X
X@item MALLOC(size)
XUsage: @code{char_pnt = MALLOC(1000);}.  This is like ALLOC but for
Xcharacters only.  It means allocate space for 1000 characters.
X
X@item CALLOC(type, count)
XUsage: @code{infp = CALLOC(struct info_st, 100);}.  This means allocate
Xspace for 100 info_st structures and zero them all.
X
X@emph{NOTE}: the arguments for the CALLOC macro are sort of reversed
Xfrom calloc(unsigned int count, unsigned int size).
X
X@item REALLOC(pnt, type, count)
XUsage: @code{long_pnt = REALLOC(old_pnt, long, 10);}.  This takes
Xold_pnt and and changes its size to accommodate 10 longs.
X
X@item REMALLOC(pnt, size)
XUsage: @code{char_pnt = REMALLOC(char_pnt, 100);}.  This is like REALLOC
Xbut for characters only.  It takes char_pnt and changes its size to 100
Xcharacters.
X
X@item FREE(pnt)
XUsage: @code{(void)FREE(pnt);}.  This frees memory pointers.
X
X@item STRDUP(string)
XUsage: @code{char_pnt = STRDUP("hello");}.  This macro duplicates the
Xfunctionality of the @samp{strdup} function.  string can be either a
Xstatic string like "hello" or a character pointer.  Non-gcc users should
Xuse @code{STRDUP("hello", char_pnt);} where char_pnt is the variable
Xwhich will be assigned to the pointer to the copy of "hello".
X
X@item BDUP(pnt, size)
XUsage: @code{new_item_pnt = BDUP(&item, sizeof(item));}.  This allocates
Xspace for size bytes, copies size bytes from pnt into the new allocation
Xand returns it.  It is like strdup but for non-strings.  Non-gcc users
Xshould use @code{BDUP(&item, sizeof(item), new_item_pnt);} where
Xnew_item_pnt is the variable which will be assigned the pointer to the
Xcopy of item.
X@end table
X
XIn the above macro list, I have also included a STRDUP and a BDUP macro.
XSTRDUP, for those who are not familiar with the strdup function, takes a
Xstring, allocates enough information to store the string (along with its
Xnull character), and then copies the string into the new space.  This
Xmacro does not actually call strdup but provides the same functionality
Xand provides file and line memory information to the library.
X
XBDUP is a function that I invented.  I use it to duplicate structures or
Xother elements that are not strings.  A pointer to an element and its
Xsize are passed in and the macro returns an allocated copy of it.
X
Xgcc (GNUs c-compiler) has a neat feature in that it understands
Xreturn-values from macros.  I have included a gcc form of these 2 macros
X(which makes them a lot more functional) as well as a non-gcc version.
X
X@emph{NOTE}: I would like to strongly recommend the usage of gcc.  It is
Xa superior compiler and future releases of this library may require its
Xuse.
X
X@node Extensions, Disabling the Library, Allocation macros, Usage
X@section Additional Non-Standard Routines.
X
XThe library has a number of variables and routines that are not a
Xstandard part of most malloc libraries:
X
X@table @code
X@item char * malloc_logpath;
XThis variable can be used to set the malloc log filename.  The env
Xvariable MALLOC_LOGFILE overrides this variable.
X
X@item int malloc_errno;
XThis variable stores the internal malloc library error number like errno
Xdoes for the system calls.  It can be passed to @code{malloc_strerror()}
X(see below) to get a string version of the error.  It will have a value
Xof zero if the library has not detected any problems.
X
X@item void malloc_shutdown(void);
XThis routine shuts the library down and logs the final statistics and
Xinformation especially the non-freed memory pointers.  It should be run
Xright before @code{exit()} or as the last function in @code{main()}.
X
X@example
X        main()
X        @{
X                @dots{}
X                malloc_shutdown();
X                exit(0);
X        @}
X@end example
X@item int malloc_heap_map(void);
XThis routine will log to the logfile (if it is enabled) a graphical
Xrepresentation of the current heap space.  It needs some work but should
Xprovide some good information.
X
X@item int malloc_verify(char * pnt);
XUse @code{malloc_verify} to verify individual memory pointers that are
Xsuspect of memory problems.  To check the entire heap pass in a NULL or
X0 pointer.
X
X@emph{NOTE}: @samp{malloc_verify} can only check the heap with the
Xfunctions that have been enabled.  For example, if fence-post checking
Xis not enabled in the @samp{MALLOC_DEBUG} variable, @samp{malloc_verify}
Xcannot check the fence-post areas in the heap.
X
X@item int malloc_debug(long debug);
XWith this routine, the value in the @samp{MALLOC_DEBUG} variable can be
Xoverridden and the library debugging features set explicitly.  For
Xinstance, if debugging should never be enabled for a program, a call to
X@code{malloc_debug(0);} as the first call in @code{main()} will disable
Xall the memory debugging from that point on.
X
XOne problem however is that some compilers (gcc for instance) make calls
Xto memory allocation functions @emph{before} @code{main()} is reached
Xand @code{malloc_debug()} called meaning some debugging information may
Xbe generated regardless.
X
X@item int malloc_examine(char * pnt, int * size, char ** file, int * line);
XThis routine provides some very interesting functionality.  It returns
Xthe size of a pnt's allocation as well as the file and line from which
Xit was allocated.
X
X@emph{NOTE}: This function is @emph{certainly} not portable and is not
Xprovided by other malloc libraries.
X
X@item char * malloc_strerror(int errnum);
X@code{malloc_strerror} returns the string representation of the error
Xvalue in errnum (which probably should be malloc_errno).  This allows
Xthe logging of more verbose memory error messages.
X
XYou can also display the string representation of an error value by a
Xcall to the @file{malloc_dbg} program with a @samp{-e #} option
X@xref{malloc_dbg program}.
X@end table
X
X@node Disabling the Library,  , Extensions, Usage
X@section How to Compile/Link Without the Library.
X
XWhen you are finished with the development and debugging sessions, you
Xmay want to disable the malloc-debug library and put in its place either
Xthe system's memory-allocation routines, gnu-malloc, or maybe your own.
XI have tried to make this a reasonably painless process.  The ease of
Xthe extraction depends heavily on how many of the library's features
Xyour made use of during your coding.
X
XI am open to any reasonable suggestions as to how to improve this
Xprocess while maintaining the effectiveness of the debugging.
X
X@itemize @bullet
X@item
XIf you compiled any of your source modules with @code{MALLOC_FUNC_CHECK}
Xdefined then you must first recompile all those modules without the flag
Xenabled.
X
X@item
XIf you are using any of the special functions provided by the
Xmalloc-debug library (such as @code{malloc_shutdown()}), then you will
Xneed to @code{#ifdef}, remove, or comment them out of your code.
X
X@item
XIf you want to @emph{totally} disable the malloc-debug library then you
Xwill need to recompile all the C files that include @file{malloc.h}
Xwhile defining @code{MALLOC_DEBUG_DISABLE}.  This will cause the malloc
Xleap macros to not be applied @xref{Allocation macros}.
X
X@example
X        gcc -O -g -DMALLOC_DEBUG_DISABLE main.c
X@end example
X@item
XNow you are ready to relink with a new library.  If you have not
Xcompiled all your source with @code{MALLOC_DEBUG_DISABLED} defined then
Xyou need to include the @file{malloc_lp.o} file on the link line.
X
X@example
X        gcc -O -g main.o malloc_lp.o -L/usr/local/lib -lgmalloc
X@end example
XIf you have disabled malloc with the @code{MALLOC_DEBUG_DISABLED} flag
Xor never included @file{malloc.h} in any of your C files, then you will
Xnot need to include the @file{malloc_lp.o} file on the link line.
X
X@example
X        gcc -O -g main.o -L/usr/local/lib -lgmalloc
X@end example
XIf you get unresolved references like @code{_malloc_leap} or
X@code{_malloc_bcopy} then something was not disabled as it should have
Xbeen.
X@end itemize
X
X@node Code, Plugs, Usage, Top
X@chapter Information on the Source and General Concerns.
X
X@menu
X* Definitions::         Some terms and other information.
X* Compatibility::       General compatibility concerns.
X* Portability::         Issues important for porting the library.
X@end menu
X
X@node Definitions, Compatibility,  , Code
X@section Some Terms and Other Information.
X
XHere are a couple definitions and other information for those interested
Xin "picking the brain" of the library.  The code is a little ugly here
Xand there and it conforms to the Gray-Watson handbook of coding
Xstandards only.
X
X@table @dfn
X@item bblock
Xbasic block containing 2 ^ BASIC_BLOCK bytes of info
X
X@item bblock_adm
Xadministration for a set of basic blocks
X
X@item dblock
Xdivided block containing some base 2 number of blocks smaller than a
Xbasic block.
X
X@item dblock_adm
Xadministration for a set of divided blocks
X
X@item chunk
Xsome anonymous amount of memory
X@end table
X
X@node Compatibility, Portability, Definitions, Code
X@section General Compatibility Concerns.
X
X@itemize @bullet
X@item
XRealloc() backwards compatibility with being able to realloc from the
Xlast freed block is @emph{not} supported.
X
X@item
XRealloc() of a NULL pointer is supported in which case the library will
Xjust make a call to malloc().  This is a compilation option in the
X@file{conf.h} file.
X
X@item
XThe library does @emph{not} provide memalign() nor valloc() support as
Xof yet, but may in future releases.  I would be interested to know who
Xis using these functions, which architectures they are supported on, and
Xfor what reason they are being used.
X
X@item
XAside from possibly being slower than the system's memory allocation
Xfunctions, the library should be fully compatible with the standard
Xmemory routines.  If this is @emph{not} the case please bring this to my
Xattention.
X@end itemize
X
X@node Portability,  , Compatibility, Code
X@section Issues Important for Porting the Library.
X
XGeneral compatibility issues center around:
X
X@itemize @bullet
X@item
Xsbrk or compatible function usages
X@item
XWhether the systems's heap grows towards high or low memory.  The
Xchunk.c code is designed (loosely) around the fact that consecutive
Xcalls to sbrk should give higher memory addresses.
X
XI have not been able to test the library on a system whose heap grows
Xtowards low memory.  If you are trying to run the library on such a
Xsystem I would be interested in talking with you.
X@end itemize
X
X@node Plugs,  , Code, Top
X@chapter Soapbox Comments.
X
XSince I have your attention I would like to talk for a second about a
Xcouple of things that I feel strongly about.  If you would like any more
Xinformation about the below, please mail to the supplied addresses or
Xdrop me a line with any questions.
X
X@table @samp
X@item The Free Software Foundation <gnu@@prep.ai.mit.edu>
XAs you should be able to tell by now, I am a FSF supporter.  The FSF's
Xgoal, as I see and support it, is to encourage the exchange of free
Xsource code.  The organization and its individuals have volunteered an
Xamazing amount of time toward this.  If you use emacs, gcc, gdb, patch,
Xperl, bison, or any of their many programs and libraries then you have
Xbenefited from the movement.  Please consider supporting it.
X
X@item Berkeley Software Design, Inc. <bsdi-info@@bsdi.com>
XWe at the Antaire Corporation are the proud and enthusiastic owners of
Xthe BSD/386 operating system.  For $1k you get a @emph{complete}
XBSD-flavor operating system with @emph{full source} for 386 and 486
Xsystems (binary licenses are available).  Along with the obvious
Xbenefits of full source code come excellent customer support/service and
Xsystem features such as a MS-DOG runtime environment, complete tcp/ip
Xnetworking facilities including nfs, full software development
Xutilities, X, etc.
X
X@contents
X@bye
END_OF_FILE
if test 41525 -ne `wc -c <'malloc.texi'`; then
    echo shar: \"'malloc.texi'\" unpacked with wrong size!
fi
# end of 'malloc.texi'
fi
if test -f 'malloc_t.c' -a "${1}" != "-c" ; then
  echo shar: Will not clobber existing file \"'malloc_t.c'\"
else
echo shar: Extracting \"'malloc_t.c'\" \(6254 characters\)
sed "s/^X//" >'malloc_t.c' <<'END_OF_FILE'
X/*
X * test program for malloc code
X *
X * Copyright 1992 by Gray Watson and the Antaire Corporation
X *
X * This file is part of the malloc-debug package.
X *
X * This library is free software; you can redistribute it and/or
X * modify it under the terms of the GNU Library General Public
X * License as published by the Free Software Foundation; either
X * version 2 of the License, or (at your option) any later version.
X *
X * This library is distributed in the hope that it will be useful,
X * but WITHOUT ANY WARRANTY; without even the implied warranty of
X * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
X * Library General Public License for more details.
X *
X * You should have received a copy of the GNU Library General Public
X * License along with this library (see COPYING-LIB); if not, write to the
X * Free Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
X *
X * The author of the program may be contacted at [e-mail]
X */
X
X/*
X * Test program for the malloc library.  Current it is interactive although
X * probably should be script based.
X */
X
X#include <stdio.h>                /* for stdin */
X
X#include "malloc.h"
X
X#if INCLUDE_RCS_IDS
XLOCAL    char    *rcs_id =
X  "$Id: malloc_t.c,v 1.15 1993/04/06 04:24:44 gray Exp $";
X#endif
X
X#define DEFAULT_ITERATIONS    1000
X
X/*
X * hexadecimal STR to integer translation
X */
XLOCAL    int    hex_to_int(char * str)
X{
X  int        ret;
X
X  /* strip off spaces */
X  for (; *str == ' ' || *str == '\t'; str++);
X
X  /* skip a leading 0[xX] */
X  if (*str == '0' && (*(str + 1) == 'x' || *(str + 1) == 'X'))
X    str += 2;
X
X  for (ret = 0;; str++) {
X    if (*str >= '0' && *str <= '9')
X      ret = ret * 16 + (*str - '0');
X    else if (*str >= 'a' && *str <= 'f')
X      ret = ret * 16 + (*str - 'a' + 10);
X    else if (*str >= 'A' && *str <= 'F')
X      ret = ret * 16 + (*str - 'A' + 10);
X    else
X      break;
X  }
X
X  return ret;
X}
X
X/*
X * read an address from the user
X */
XLOCAL    long    get_address(void)
X{
X  char    line[80];
X  long    pnt;
X
X  do {
X    (void)printf("Enter a hex address: ");
X    (void)fgets(line, sizeof(line), stdin);
X  } while (line[0] == '\0');
X
X  pnt = hex_to_int(line);
X
X  return pnt;
X}
X
XEXPORT    int    main(int argc, char ** argv)
X{
X  argc--, argv++;
X
X  (void)srand(time(0) ^ 0xDEADBEEF);
X
X  (void)printf("------------------------------------------------------\n");
X  (void)printf("Malloc test program.  Type 'help' for assistance.\n");
X
X  for (;;) {
X    int        len;
X    char    line[128], *linep;
X
X    (void)printf("------------------------------------------------------\n");
X    (void)printf("prompt> ");
X    (void)fgets(line, sizeof(line), stdin);
X    linep = (char *)index(line, '\n');
X    if (linep != NULL)
X      *linep = '\0';
X
X    len = strlen(line);
X    if (len == 0)
X      continue;
X
X    if (strncmp(line, "?", len) == 0
X    || strncmp(line, "help", len) == 0) {
X      (void)printf("------------------------------------------------------\n");
X      (void)printf("HELP:\n\n");
X
X      (void)printf("help      - print this message\n\n");
X
X      (void)printf("malloc    - allocate memory\n");
X      (void)printf("free      - deallocate memory\n");
X      (void)printf("realloc   - reallocate memory\n\n");
X
X      (void)printf("map       - map the heap to the logfile\n");
X      (void)printf("overwrite - overwrite some memory to test errors\n");
X      (void)printf("random    - randomly execute a number of malloc/frees\n");
X      (void)printf("verify    - check out a memory address\n\n");
X
X      (void)printf("quit      - quit this test program\n");
X      continue;
X    }
X
X    if (strncmp(line, "quit", len) == 0)
X      break;
X
X    if (strncmp(line, "malloc", len) == 0) {
X      int    size;
X
X      (void)printf("How much: ");
X      (void)fgets(line, sizeof(line), stdin);
X      size = atoi(line);
X      (void)printf("malloc(%d) returned: %#lx\n", size, (long)MALLOC(size));
X      continue;
X    }
X
X    if (strncmp(line, "free", len) == 0) {
X      long    pnt;
X
X      pnt = get_address();
X      (void)printf("free(%#lx) returned: %s\n",
X           pnt, (FREE(pnt) == FREE_NOERROR ? "success" : "failure"));
X      continue;
X    }
X
X    if (strncmp(line, "realloc", len) == 0) {
X      int    size;
X      long    pnt;
X
X      pnt = get_address();
X
X      (void)printf("How much: ");
X      (void)fgets(line, sizeof(line), stdin);
X      size = atoi(line);
X
X      (void)printf("realloc(%#lx, %d) returned: %#lx\n",
X           pnt, size, (long)REMALLOC(pnt, size));
X
X      continue;
X    }
X
X    if (strncmp(line, "map", len) == 0) {
X      (void)malloc_heap_map();
X      (void)printf("Done.\n");
X      continue;
X    }
X
X    if (strncmp(line, "overwrite", len) == 0) {
X      long    pnt, magic;
X
X      pnt = get_address();
X
X      magic = 0x12345678;
X      bcopy(&magic, (char *)pnt, sizeof(magic));
X
X      (void)printf("Done.\n");
X      continue;
X    }
X
X    /* do random heap hits */
X    if (strncmp(line, "random", len) == 0) {
X      int    count, max;
X
X      (void)printf("How many iterations[%d]: ", DEFAULT_ITERATIONS);
X      (void)fgets(line, sizeof(line), stdin);
X      if (line[0] == '\0' || line[0] == '\n')
X    max = DEFAULT_ITERATIONS;
X      else
X    max = atoi(line);
X
X      for (count = 1; count < max; count += 10) {
X    int    amount;
X    char    *data;
X
X    amount = rand() % (count * 10) + 1;
X    data = MALLOC(amount);
X    (void)FREE(data);
X      }
X
X      (void)printf("Done.\n");
X      continue;
X    }
X
X    if (strncmp(line, "verify", len) == 0) {
X      long    pnt;
X      int    ret;
X
X      pnt = get_address();
X
X      ret = malloc_verify((char *)pnt);
X      (void)printf("malloc_verify(%#lx) returned: %s\n",
X           pnt,
X           (ret == MALLOC_VERIFY_NOERROR ? "success" : "failure"));
X      continue;
X    }
X
X    (void)printf("Unknown command '%s'.\n", line);
X    (void)printf("Type 'help' for assistance.\n");
X  }
X
X  /* shutdown the alloc routines */
X  malloc_shutdown();
X
X  (void)printf("------------------------------------------------------\n");
X  (void)printf("final malloc_verify returned: %s\n",
X           (malloc_verify(NULL) == MALLOC_VERIFY_NOERROR ? "success" :
X        "failure"));
X  (void)printf("------------------------------------------------------\n");
X
X  exit(0);
X}
END_OF_FILE
if test 6254 -ne `wc -c <'malloc_t.c'`; then
    echo shar: \"'malloc_t.c'\" unpacked with wrong size!
fi
# end of 'malloc_t.c'
fi
if test -f 'mallocrc' -a "${1}" != "-c" ; then
  echo shar: Will not clobber existing file \"'mallocrc'\"
else
echo shar: Extracting \"'mallocrc'\" \(3302 characters\)
sed "s/^X//" >'mallocrc' <<'END_OF_FILE'
X#
X# Sample Malloc rc file for the debug malloc library
X# Rename this to .mallocrc and place in your home directory to activate.
X# See malloc.info for more information
X#
X# $Id: mallocrc,v 1.7 1993/04/05 22:30:25 gray Exp $
X#
X
X#
X# Lines in this file should have the form:
X#
X#    tag    token1, token2, ...
X#
X# The above 'tag' is then passed to the 'malloc' alias to set the current
X# debugging functionality to token1, token2, ...
X#
X# Tag lines can be finished with a \ meaning it continues onto the next line.
X# Lines begining with '#' or empty lines are ignored
X#
X
X#
X# Token:            Description:
X###########################################################################
X# none                no debuging functionality
X#
X# log-stats            log general statistics
X# log-non-free            log non-freed memory pointers on shutdown
X# log-perror            log error codes and messages
X# log-trans            log memory transactions
X# log-bad-pnt            log information about bad-pointers
X# log-admin            log full administrative information
X# log-blocks            log detailed block information in heap_map
X# log-unknown            log unknown non-freed memory pointers too
X#
X# check-fence            check fence-post areas
X# check-heap            do general heap checking
X# check-lists            verify internal heap linked-lists
X# check-dblock            do detailed checking on small allocations
X# check-dblock-fence        check the fence-post areas of small allocations
X# check-free            check to see if free space has been overwritten
X# check-funcs            check the arguments of some routines
X#
X# realloc-copy            always copy data to a new pointer when realloc
X# free-blank            overwrite space that is freed
X# error-abort            abort the program (and dump core) on errors
X# alloc-blank            overwrite space that is to be alloced
X# heap-check-map        log a heap-map every time the heap is checked
X# print-perror            dump errors and messages to STDERR
X#
X
X# no debugging
Xnone    none
X
X# basic production
Xproduction    log-stats, log-non-free, log-perror, log-bad-pnt
X
X# basic runtime
Xruntime        log-stats, log-non-free, log-perror, log-bad-pnt, \
X        check-fence
X
X# more logging and some heap checking
X2        log-stats, log-non-free, log-perror, log-trans, log-bad-pnt, \
X        check-fence, check-heap, check-lists, check-dblock-fence, \
X        error-abort
X
X# good checking functionality
X3        log-stats, log-non-free, log-perror, log-trans, log-bad-pnt, \
X        log-admin, log-blocks, \
X        check-fence, check-heap, check-lists, check-dblock-fence,
X        check-funcs, \
X        realloc-copy, free-blank, alloc-blank, error-abort
X
X# extensive checking
X4        log-stats, log-non-free, log-perror, log-trans, log-bad-pnt, \
X        log-admin, log-blocks, \
X        check-fence, check-heap, check-lists, check-dblock, \
X        check-fence-dblock, check-funcs, \
X        realloc-copy, free-blank, alloc-blank, error-abort
X
X# ultra-extensive checking
X5        log-stats, log-non-free, log-perror, log-trans, log-bad-pnt, \
X        log-admin, log-blocks, \
X        check-fence, check-heap, check-lists, check-dblock, \
X        check-dblock-fence, check-free, check-funcs, \
X        realloc-copy, free-blank, alloc-blank, error-abort
X
X# full fence-post checking
Xfence        log-stats, log-non-free, log-perror, log-bad-pnt, \
X        check-fence, check-dblock-fence
X
X# full logging of statistics to logfile and screen
Xlog        log-stats, log-non-free, log-perror, log-trans, log-bad-pnt, \
X        log-admin, log-blocks, \
X        check-fence, \
X        heap-check-map, print-perror
END_OF_FILE
if test 3302 -ne `wc -c <'mallocrc'`; then
    echo shar: \"'mallocrc'\" unpacked with wrong size!
fi
# end of 'mallocrc'
fi
echo shar: End of archive 4 \(of 5\).
cp /dev/null ark4isdone
MISSING=""
for I in 1 2 3 4 5 ; do
    if test ! -f ark${I}isdone ; then
    MISSING="${MISSING} ${I}"
    fi
done
if test "${MISSING}" = "" ; then
    echo You have unpacked all 5 archives.
    echo "Do a 'sh ./configure' to configure the library"
    rm -f ark[1-9]isdone
else
    echo You still need to unpack the following archives:
    echo "        " ${MISSING}
fi
##  End of shell archive.
exit 0