Using Pretty-Printing

Pretty-printing lets your program provide its own rendition of an expression's value through a function call. If you specify the -p option to the print command, rprint command, display command, or watch command, dbx searches for a function of the form const chars *db_pretty_print(const T *, int flags, const char *fmt) and calls it, substituting the returned value for print or display.

The value passed in the flags argument of the function is bit-wise or one of the following:

The db_pretty_print() function can be either a static member function or a standalone function.

If the dbx environment variable output_pretty_print is set to on, -p is passed to the print command, rprint command, or display command as the default. Use +p to override this behavior.

Consider also the following:

• Prior to version 7.6 pretty-printing was based on a ksh implementation of prettyprint. While this ksh function (and its pre-defined alias pp) still exist, most of the semantics have been reimplemented inside dbx with the following results:

  • For the IDE, the ability of watches, local variables, and balloon evaluation to utilize pretty-printing.

  • In the print command, display command, and watch command, the -p option uses the native route.

  • Better scalability, especially now that pretty-printing can be called quite often, especially for watches and local variables.

  • Better opportunity to derive addresses from expressions.

  • Better error recovery.

• For const/volatile unqualified types, in general, functions such as db_pretty_print(int *, ...() and db_pretty_print(const int *, ...)() are considered distinct. The overload resolution approach of dbx is discerning but non-enforcing:

  • Discerning. If you have defined variables declared both int and const int, each will be routed to the appropriate function.

  • Non-enforcing. If you have only one int or const int variable defined, they will match with both functions. This behavior is not specific to pretty-printing and applies to any calls.

• Pretty-print functions are invoked for the following:

  • print -p or if the dbx environment variable output_pretty_print is set to on.

  • display -p or if the dbx environment variable output_pretty_print is set to on.

  • watch -p or if the dbx environment variable output_pretty_print is set to on.

  • Balloon evaluation if the dbx environment variable output_pretty_print is set to on.

  • Local variable if the dbx environment variable output_pretty_print is set to on.

• Pretty-print functions are not invoked for the following:

  • $[]. The rationale is that $[] is intended to be used in scripts and need to be predictable.

  • The dump command. dump uses the same simplified formatting as the where command, which may be converted to use pretty-printing in the future. This limitation does not apply to the Local Variables widow in the IDE.

• Nested values will not be pretty-printed because dbx does not have the infrastructure to calculate the addresses of nested fields.

• The db_pretty_print() must be compiled with the -g option because dbx needs access to parameter signatures.

• The db_pretty_print() function is allowed to return NULL.

• The main pointer passed to the db_pretty_print() function is guaranteed to be non-NULL but otherwise it may still point to a poorly initialized object.

• The dbx environment variable output_pretty_print_fallback is set by default to on, meaning that dbx will fall back on regular formatting if pretty-printing fails. If the environment variable is set to off, dbx will issue an error message if pretty-printing fails.

• Pretty-printing might fail for one of these detectable and recoverable reasons:

  • No pretty-print function found.

  • The expression to be pretty-printed cannot have its address taken.

  • The function call did not immediately return, which would imply a segmentation fault resulting when the pretty-print function is not robust when encountering bad objects. It could also imply a user breakpoint.

  • The pretty-print function returned NULL.

  • The pretty-print function returned a pointer that dbx fails to indirect through.

  • A core file is being debugged.

  For all cases except the function call not immediately returning, the above failures are silent and dbx falls back on regular formatting. But if the output_pretty_print_fallback environment variable is set to off, dbx will issue an error message if pretty-printing fails.

  However, if you use the print -p command rather than setting the dbx environment variable output_pretty_print to on, dbx stops in the broken function and allows you to diagnose the cause of failure. You can then use the pop -c command to clean up the call.

• The db_pretty_print() function needs to be disambiguated based on the type of its first parameter. In C, you can overload functions by writing them as file statics.