You can annotate Purify's output in order to help reproduce a particular run, track down an error, or relate events or phases in your program to error messages. You can also record environmental or situational details into a log file or view file to help decode the results of a test run.
For example, you can record the current directory name and the command line arguments into a log file or view file when running a batch of tests. This allows you to see how to repeat a particular run of your program if that particular run generated an error.
In an interactive program, you might record the commands issued by the user into Purify's output in order to identify the user interactions that triggered the Purify messages.
You can use these functions to annotate Purify's output:
Use purify_printf (char *fmt, ...) to add an annotation to all forms of Purify output.
Use purify_logfile_printf (char *fmt, ...) to add an annotation if the output goes to a log file.
If the
output is going to a view file, the annotation from purify_logfile_printf
is recorded in the view file but not displayed. To print the annotation
in the Viewer, specify:
% purify -view -logfile=<filename>.plog <filename>.pv
Use purify_printf_with_call_chain (char *fmt, ...) to add an annotation similar to purify_printf, and also include the call chain. This has the effect of counting as an error, triggering mail if -mail-to-user is set. You can use this function from within your error handler functions. It is useful for copying the error message to the log file and reporting the call chain that caused the error to happen.
Each of these functions takes a format string and a variable number of arguments, just like printf.
Purify provides partial support for the % conversion syntax of printf. You can use the simple conversion characters %d, %u, %n, %s, %c, %e, %f, or %g. No field width or precision specifiers are allowed, however, and the %e, %f, %g conversion characters are equivalent to %10.2f.
You can also annotate Purify output by using the option -copy-fd-output-to-logfile. The option's value is a list of file-descriptor numbers, for example: 1,2. This causes Purify to interleave all output written to file descriptors 1 and 2 with the Purify output.