7.1 Library behaviour

Most of the behaviour of the mpatrol library can be controlled at run-time via options which are read from the MPATROL_OPTIONS environment variable. This prevents you having to recompile or relink each time you want to change a library setting, and so makes it really easy to try out different settings to locate a particular bug. You should know how to set the value of an environment variable on your system before you read on.

By default, the mpatrol library will attempt to determine the minimum required alignment for any generic memory allocation when it first initialises itself. This may be affected by the compiler and its settings when the library was built but it should normally reflect the minimum alignment required by the processor on your system. If you would prefer a larger (or perhaps even smaller) default alignment you may change it at run-time using the DEFALIGN option. The value you supply must be in bytes, must be a power of two, and should not be larger that the system page size. If you encounter bus errors due to misaligned memory accesses then you should increase this value.

On systems that have virtual memory the library will attempt to write-protect all of its internal structures when user code is being run. This ensures that it is nearly impossible for a program to corrupt any mpatrol library data. However, unprotecting and then protecting the structures at every library call has a slight overhead so you may prefer to disable this behaviour by using the NOPROTECT option. This has no effect on systems that have no virtual memory.

Usually it is desirable for many system library routines to be protected from being interrupted by certain signals since they may themselves be called from signal handlers. If this is not the case then it may be possible to interrupt the program from within such routines, perhaps causing problems if their global variables are left in an undefined state. As the mpatrol library replaces some of these system library routines it is also possible to specify that they are protected from certain interrupt signals using the SAFESIGNALS option. However, this can sometimes result in it being hard to interrupt the program from the keyboard if a lot of processor time is spent in mpatrol routines, which is why this behaviour is disabled by default¹.

On UNIX platforms, the fork() function can cause problems if it is used to make a copy of the parent process without immediately calling one of the exec() family of functions. This is because the child process inherits all of the memory allocations of the parent process, but also inherits the log, profile and trace files as well. If both the parent and child processes make subsequent memory allocations there will be multiple entries with the same allocation indices written to the log, profile or trace files. This can be most confusing when processing these files afterwards! As a workaround, the mpatrol library will always check the current process identifier every time one of its functions is called if the CHECKFORK option is used and will open new log, profile or trace files if it has determined that the process has been forked. If the CHECKFORK option is not used then a call to __mp_reinit() should be added as the first function call in the child process in order to duplicate the behaviour of the CHECKFORK option.

On UNIX systems, the usual way for malloc libraries to allocate memory from the process heap is through the sbrk() system call. This allocates memory from a contiguous heap, but has the disadvantage in that other library functions may also allocate memory using the same function, thus creating holes in the heap. This is not a problem for mpatrol, but you may have a suspicion that your bug is due to a function from another library corrupting your data so you may wish to use the USEMMAP option. This is only available on systems that have the mmap() system call and allows mpatrol to allocate all of its memory from a part of the process heap that is non-contiguous (i.e. each call to mmap() may return a block of memory that is completely unrelated to that returned by the previous call). It may also be required on some systems in order for the mpatrol library to implement memory protection.

Beginning with release 1.3.3, the mpatrol library now allocates its internal memory in the opposite way to user memory on UNIX systems that support the mmap() system call. This means that by default, user memory is allocated with sbrk() whereas internal memory is allocated with mmap(), and this behaviour is reversed when the USEMMAP option is used. This was done to segregate user memory from internal memory, and was especially required for the mptrace command's graphical display.

The CHECK option allows you to specify that every time an mpatrol library function is called the library will automatically check the freed memory and overflow buffers of every memory allocation, although this can slow program execution down, especially if you suspect the error you are looking for occurs at the 1000th memory allocation, for example. You can therefore use the CHECK option to specify a range of memory allocations at which the mpatrol library will automatically check the freed memory and overflow buffers. All other allocations that fall outside this range will not be checked. You can also specify an optional frequency at which this checking should be performed. No such checking is performed by default in mpatrol release 1.4.0 and onwards — you must specify CHECK=- to get the original behaviour.

On UNIX systems, the mpatrol library can also invoke the mpedit command to edit source files that show up in any warnings or error messages that it generates. This can only happen if the diagnostic message can be traced back to a specific source line in the program; in many cases this is not possible. If editing the files is not required, a context listing of the appropriate source line can be generated instead. The EDIT option specifies that files are to be edited and the LIST option specifies that a context listing is to be generated. These options are mutually exclusive.

If the mpatrol library that was built for your system supports reading symbolic information from a program's executable file, but it cannot locate the executable file, or you wish to specify an alternative, you can use the PROGFILE option to do this. All this does is instruct the mpatrol library to read symbols from this file instead. Note that on systems that support dynamic linking, the library can also read symbols from a dynamically linked executable file that has had its normal symbol table stripped.

Finally, a list of all of the recognised options in the mpatrol library can be displayed to the standard error file stream by using the HELP option. This will not affect the settings of the library in any way, so you should be able to use other options at the same time.