MALLOC_SS(3)MALLOC_SS(3) NAME calloc, free, malloc, memalign, realloc, ssmalloc_error, valloc - SpeedShop memory allocation library SYNOPSIS #include <stdlib.h> void *calloc (size_t nelem, size_t elsize); void free (void *ptr); void *malloc (size_t size); void *memalign (size_t alignment, size_t size); void *realloc (void *ptr, size_t size); void ssmalloc_error (char *message); void *valloc (size_t size); IMPLEMENTATION IRIX systems DESCRIPTION The SpeedShop Performance Tools contain a malloc library, libmalloc_ss.so, that provides tracing information and detects errors around calls to the various malloc routines. The library provides an intercept layer for calls to the following routines: free, malloc, memalign, realloc, and valloc. This intercept layer allows the SpeedShop performance tools to trace all calls, as follows: * Calls to free, malloc, and realloc are passed to the memory allocation library that the program is linked with. * Calls to calloc are not actually intercepted. These calls rely on the underlying calloc to call malloc to allocate space. * Calls to memalign are implemented by allocating a block large enough to hold the aligned area asked for by the user, a guard area that holds a flag indicating that the user block was obtained through memalign, and the address of the larger block. * Calls to valloc are translated into a call to getpagesize(2), followed by a memalign call. * Calls to ssmalloc_error cannot be made by a user program. This is not a user-accessible function. It is intended for internal use by SpeedShop utilities. It is called when an error is detected. MALLOC TRACING The library provides for tracing of all calls to any of the entry points listed previously, as well as any of the errors described in the ERROR DETECTION section of this man(1) page. The trace is normally captured using a SpeedShop performance experiment. It may be written in ASCII to stderr by enabling the environment variable _SSMALLOC_TRACING, although this typically produces a great deal of output. ERROR DETECTION The library detects some errors under all conditions. It detects others if _SSMALLOC_FASTCHK error detection is enabled. All errors pass through the routine ssmalloc_error, and a trap can be placed at the exit from that routine to catch the problem. Errors are also traced. The errors that are always detected are as follows: * malloc call failing (returning NULL). * realloc call failing (returning NULL). * realloc call with an address outside the range of heap addresses returned by malloc or memalign. * memalign call with an improper alignment. * free call with an address that is improperly aligned. * free call with an address outside the range of heap addresses returned by malloc or memalign. If _SSMALLOC_FASTCHK is enabled, the library also detects the following: * free or realloc calls in which the words prior to the user block have been corrupted. * free or realloc calls in which the words following the user block have been corrupted. * free or realloc calls in which the address is that of a block that has already been freed. This error may not always be detected if the area around the block is reallocated after it was first freed. ENVIRONMENT VARIABLES The behavior of the library is governed by the following various environment variables: * _SPEEDSHOP_VERBOSE. If set to a zero-length string, messages are printed to stderr only when an error occurs. If set to a nonzero length string, detailed information about all traced events, including the callstack at the time the error was detected, is printed. This option is not normally used by the end user, as it can produce a huge volume of output. * _SSMALLOC_TRACING. Enables tracing of all calls through the library. Tracing is normally done in the course of a performance experiment; the variable need not be set in such cases, as the running of the experiment will automatically enable it. If the option is enabled when the program is run independently and _SSMALLOC_VERBOSE is set to 2 or greater, the trace events and program call stacks are written to stderr. * _SSMALLOC_FASTCHK. Enables corruption detection for library calls. Corruption detection is done by allocating a space larger than the requested area and putting specific patterns in front of and behind the area returned to the caller. When free is called, the patterns are checked. If the area was overwritten, an error message is printed using an internal call to the routine ssmalloc_error. Under the debugger, a trap may be set at exit from this routine to catch the program at the error. * _SSMALLOC_FULLWARN. Enables detection of some calls that are not strictly errors but represent sloppy programming, including free(NULL), malloc(0), and realloc(ptr,0). * _SSMALLOC_MAXMALLOC n. For n, specify a nonzero integer in any base. Sets a maximum size for any malloc, realloc, or memalign allocation. Any request exceeding that size is flagged as an error and returns a NULL pointer. Setting _SSMALLOC_MAXMALLOC to zero disables the test. Note that the size argument to malloc is an unsigned variable. A small negative number is treated as a very large unsigned number. It typically triggers the error described in the previous paragraph if _SSMALLOC_MAXMALLOC is set. * _SSMALLOC_NO_REUSE. Specifies that no area that has been freed will be reused. With this option enabled, no actual free calls are really made, and the process space and swap requirements can grow quite large. * _SSMALLOC_CLEAR_FREE. Clears the data upon any free call. _SSMALLOC_FASTCHK must also be enabled. * _SSMALLOC_CLEAR_FREE_PATTERN pattern. Specifies a pattern to clear the data if _SSMALLOC_CLEAR_FREE is enabled. The default pattern is 0xcafebeef for the 32-bit version, and 0xcafebeefcafebeef for the 64-bit versions. Only full words (double words for 64 bits) are cleared to pattern. * _SSMALLOC_CLEAR_MALLOC. Clears the memory area upon each allocation. _SSMALLOC_FASTCHK must also be enabled. * _SSMALLOC_CLEAR_MALLOC_PATTERN pattern. Specifies a pattern to clear the data if _SSMALLOC_CLEAR_MALLOC is enabled. The default pattern is 0xfacebeef for the 32-bit version and 0xfacebeeffacebeef for the 64-bit versions. Only full words (double words for 64 bits) are cleared to pattern. * _SSMALLOC_NO_BUFFERING. For multiprocessor applications, disables the common buffering of heap trace data into experiment files. With buffering enabled (the default), the experiment file for each process will contain data from all processes in the shared group. If this environment variable is set, buffering is disabled, and the experiment file for each process will contain heap trace data only from its own process. SpeedShop run-time I/O buffering will still be in effect for the recording of the experiment file regardless of this environment variable. This variable only controls the internal buffering of SEE ALSO prof(1), rld(1), speedshop(1), ssdump(1), ssrun(1). getpagesize(2). malloc(3C), malloc(3X).