3.4 Additional Non-standard Routines

The library has a number of variables that are not a standard part of most malloc libraries:

int dmalloc_errno

This variable stores the internal dmalloc library error number like errno does for the system calls. It can be passed to dmalloc_strerror() (see below) to get a string version of the error. It will have a value of zero if the library has not detected any problems.

char * dmalloc_logpath

This variable can be used to set the dmalloc log filename. The env variable DMALLOC_LOGFILE overrides this variable.

Additionally the library provides a number of non-standard malloc routines:

Function:

void dmalloc_shutdown ( void )

This function shuts the library down and logs the final statistics and information especially the non-freed memory pointers. The library has code to support auto-shutdown if your system has the on_exit() call, atexit() call, or compiler destructor support (see `conf.h'). If you do not have these, then dmalloc_shutdown should be called right before exit() or as the last function in main().

main() { … dmalloc_shutdown(); exit(0); }

Function:

int dmalloc_verify ( char * pnt )

This function verifies individual memory pointers that are suspect of memory problems. To check the entire heap pass in a NULL or 0 pointer. The routine returns DMALLOC_VERIFY_ERROR or DMALLOC_VERIFY_NOERROR.

NOTE: `dmalloc_verify()' can only check the heap with the functions that have been enabled. For example, if fence-post checking is not enabled, `dmalloc_verify()' cannot check the fence-post areas in the heap.

Function:

unsigned int dmalloc_debug ( const unsigned int flags )

This routine sets the debug functionality flags and returns the previous flag value. It is helpful in server or cgi-bin programs where environmental variables cannot be used. See section Debugging Memory in a Server or Cgi-Bin Process. For instance, if debugging should never be enabled for a program, a call to dmalloc_debug(0) as the first call in main() will disable all the memory debugging from that point on.

NOTE: you cannot add or remove certain flags such as signal handlers since they are setup at initialization time only.

NOTE: you can also use dmalloc_debug_setup below.

Function:

unsigned int dmalloc_debug_current ( void )

This routine returns the current debug functionality value value. This allows you to save a copy of the debug dmalloc settings to be changed and then restored later.

Function:

void dmalloc_debug_setup ( const char * options_str )

This routine sets the global debugging functionality as an option string. Normally this would be passed in in the DMALLOC_OPTIONS environmental variable. This is here to override the env or for circumstances where modifying the environment is not possible or does not apply such as servers or cgi-bin programs. See section Debugging Memory in a Server or Cgi-Bin Process.

Some examples:

/* debug tokens high, threaded lock-on at 20, log to dmalloc.%p (pid) */ dmalloc_debug_setup("debug=0x4f46d03,lockon=20,log=dmalloc.%p"); /* turn on some debug tokens directly and log to the file 'logfile' */ dmalloc_debug_setup("log-stats,log-non-free,check-fence,log=logfile");

Function:

int dmalloc_examine ( const DMALLOC_PNT pnt, DMALLOC_SIZE * user_size_p, DMALLOC_SIZE * total_size_p, char ** file_p, int * line_p, DMALLOC_PNT * ret_addr_p, unsigned long * user_mark_p, unsigned long * seen_p )

This function returns the size of a pointer's allocation as well as the total size given including administrative overhead, file and line or the return-address from where it was allocated, the last pointer when the pointer was "used", and the number of times the pointer has been "seen". It will return DMALLOC_NOERROR or DMALLOC_ERROR depending on whether pnt is good or not.

NOTE: This function is certainly not provided by most if not all other malloc libraries.

Function:

void dmalloc_track ( const dmalloc_track_t track_func )

Register an allocation tracking function which will be called each time an allocation occurs. Pass in NULL to disable. To take a look at what information is provided, see the dmalloc_track_t function typedef in dmalloc.h.

Function:

unsigned unsigned long dmalloc_mark ( void )

Return to the caller the current "mark" which can be used later to log the pointers which have changed since this mark with the dmalloc_log_changed function. Multiple marks can be saved and used.

This is very useful when using the library with a server which does not exit. You can then save a mark before a transaction or event happens and then check to see what has changed using the dmalloc_log_changed function below. See section Debugging Memory in a Server or Cgi-Bin Process.

If you LOG_ITERATION enabled in your `settings.h' file then the entries in the log file will be prepended with the number of memory transactions that the library has handled so far. You can also enable LOG_PNT_ITERATION in `settings.h' to store the memory transaction number with each pointer.

Function:

unsigned unsigned long dmalloc_memory_allocated ( void )

Return to the caller the total number of bytes that have been allocated by the library. This is not the current in use but the total number of bytes returned by allocation functions.

Function:

unsigned unsigned int dmalloc_page_size ( void )

Return to the caller the memory page-size being used by the library. This should be the same value as the one returned by the getpagesize() function, if available.

Function:

unsigned unsigned long dmalloc_count_changed ( const unsigned long mark, const int not_freed_b, const int free_b )

Count the pointers that have changed since the mark which was returned by dmalloc_mark. If not_freed_b is set to non-0 then count the pointers that have not been freed. If free_b is set to non-0 then count the pointers that have been freed.

This can be used in conjunction with the dmalloc_mark() function to help servers which never exit ensure that transactions or events are not leaking memory. See section Debugging Memory in a Server or Cgi-Bin Process.

unsigned long mark = dmalloc_mark() ; … assert(dmalloc_count_changed(mark, 1, 0) == 0) ;

Function:

void dmalloc_log_stats ( void )

This routine outputs the current dmalloc statistics to the log file.

Function:

void dmalloc_log_unfreed( void )

This function logs the unfreed-memory information to the log file. This is also useful to log the currently allocated points to the log file to be compared against another dump later on.

Function:

void dmalloc_log_changed ( const unsigned long mark, const int not_freed_b, const int freed_b, const int details_b )

Log the pointers that have changed since the mark which was returned by dmalloc_mark. If not_freed_b is set to non-0 then log the pointers that have not been freed. If free_b is set to non-0 then log the pointers that have been freed. If details_b set to non-0 then log the individual pointers that have changed otherwise just log the summaries.

This can be used in conjunction with the dmalloc_mark() function to help servers which never exit find transactions or events which are leaking memory. See section Debugging Memory in a Server or Cgi-Bin Process.

Function:

void dmalloc_vmessage ( const char * format, va_list args )

Write a message into the dmalloc logfile using vprintf-like arguments.

Function:

void dmalloc_message ( const char * format, ... )

Write a message into the dmalloc logfile using printf-like arguments.

Function:

const char * dmalloc_strerror ( const int error_number )

This function returns the string representation of the error value in error_number (which probably should be dmalloc_errno). This allows the logging of more verbose memory error messages.

You can also display the string representation of an error value by a call to the `dmalloc' program with a `-e #' option. See section Dmalloc Utility Program.

This document was generated by Gray Watson on May, 16 2007 using texi2html 1.76.

This work is licensed by Gray Watson under the Creative Commons Attribution-Share Alike 3.0 License.
This page should be W3C Valid XHTML and should work with most browsers.