www.delorie.com/gnu/docs/gdb/gdbint_22.html

search

	Buy the book!

GDB Internals

4.2.4 Item Output Functions

The functions described below produce output for the actual data items, or fields, which contain information about the object.

Choose the appropriate function accordingly to your particular needs.

Function: void ui_out_field_fmt (struct ui_out *uiout, char *fldname, char *format, ...)

This is the most general output function. It produces the representation of the data in the variable-length argument list according to formatting specifications in format, a printf-like format string. The optional argument fldname supplies the name of the field. The data items themselves are supplied as additional arguments after format.

This generic function should be used only when it is not possible to use one of the specialized versions (see below).

Function: void ui_out_field_int (struct ui_out *uiout, const char *fldname, int value)

This function outputs a value of an int variable. It uses the "%d" output conversion specification. fldname specifies the name of the field.

Function: void ui_out_field_core_addr (struct ui_out *uiout, const char *fldname, CORE_ADDR address)

This function outputs an address.

Function: void ui_out_field_string (struct ui_out *uiout, const char *fldname, const char *string)

This function outputs a string using the "%s" conversion specification.

Sometimes, there's a need to compose your output piece by piece using functions that operate on a stream, such as value_print or fprintf_symbol_filtered. These functions accept an argument of the type struct ui_file *, a pointer to a ui_file object used to store the data stream used for the output. When you use one of these functions, you need a way to pass their results stored in a ui_file object to the ui_out functions. To this end, you first create a ui_stream object by calling ui_out_stream_new, pass the stream member of that ui_stream object to value_print and similar functions, and finally call ui_out_field_stream to output the field you constructed. When the ui_stream object is no longer needed, you should destroy it and free its memory by calling ui_out_stream_delete.

Function: struct ui_stream *ui_out_stream_new (struct ui_out *uiout)

This function creates a new ui_stream object which uses the same output methods as the ui_out object whose pointer is passed in uiout. It returns a pointer to the newly created ui_stream object.

Function: void ui_out_stream_delete (struct ui_stream *streambuf)

This functions destroys a ui_stream object specified by streambuf.

Function: void ui_out_field_stream (struct ui_out *uiout, const char *fieldname, struct ui_stream *streambuf)

This function consumes all the data accumulated in streambuf->stream and outputs it like ui_out_field_string does. After a call to ui_out_field_stream, the accumulated data no longer exists, but the stream is still valid and may be used for producing more fields.

Important: If there is any chance that your code could bail out before completing output generation and reaching the point where ui_out_stream_delete is called, it is necessary to set up a cleanup, to avoid leaking memory and other resources. Here's a skeleton code to do that:

struct ui_stream *mybuf = ui_out_stream_new (uiout); struct cleanup *old = make_cleanup (ui_out_stream_delete, mybuf); ... do_cleanups (old);

If the function already has the old cleanup chain set (for other kinds of cleanups), you just have to add your cleanup to it:

mybuf = ui_out_stream_new (uiout); make_cleanup (ui_out_stream_delete, mybuf);

Note that with cleanups in place, you should not call ui_out_stream_delete directly, or you would attempt to free the same buffer twice.