Oracle® Solaris Studio 12.4: Debugging a Program With dbx

Exit Print View

Updated: January 2015
 
 

Call-Based Pretty-Printing

Call-based pretty-printing enables an application to 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:

FVERBOSE
0x1
Not currently implemented, always set
FDYNAMIC
0x2
-d
FRECURSE
0x4
-r
FFORMAT
0x8
-f (if set, fmt is the format part)
FLITERAL
0x10
-l

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

    When pretty-printing, consider also the following information:

  • Possible Failures

  • Pretty-Printing Function Considerations

  • Prior to dbx 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, watches, local variables, and balloon evaluation can use 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.

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

  • The dbxenv 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 Function Considerations

When using the pretty-printing functions, you will need to consider the following:

  • 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.

  • The db_pretty_print() function 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 might still point to a poorly initialized object.

  • 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.

Possible Failures

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, these failures are silent and dbx falls back on regular formatting. But if the output_pretty_print_fallback dbxenv variable is set to off, dbx will issue an error message if pretty-printing fails.

If you use the print –p command rather than setting the dbxenv variable output_pretty_print to on, dbx stops in the broken function to enable you to diagnose the cause of failure. You can then use the pop –c command to clean up the call.