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

search

	Buy the book!

GDB Internals

4.2.3 Table, Tuple and List Functions

This section introduces ui_out routines for building lists, tuples and tables. The routines to output the actual data items (fields) are presented in the next section.

To recap: A tuple is a sequence of fields, each field containing information about an object; a list is a sequence of fields where each field describes an identical object.

Use the table functions when your output consists of a list of rows (tuples) and the console output should include a heading. Use this even when you are listing just one object but you still want the header.

Tables can not be nested. Tuples and lists can be nested up to a maximum of five levels.

The overall structure of the table output code is something like this:

ui_out_table_begin ui_out_table_header ... ui_out_table_body ui_out_tuple_begin ui_out_field_* ... ui_out_tuple_end ... ui_out_table_end

Here is the description of table-, tuple- and list-related ui_out functions:

Function: void ui_out_table_begin (struct ui_out *uiout, int nbrofcols, int nr_rows, const char *tblid)

The function ui_out_table_begin marks the beginning of the output of a table. It should always be called before any other ui_out function for a given table. nbrofcols is the number of columns in the table. nr_rows is the number of rows in the table. tblid is an optional string identifying the table. The string pointed to by tblid is copied by the implementation of ui_out_table_begin, so the application can free the string if it was malloced.

The companion function ui_out_table_end, described below, marks the end of the table's output.

Function: void ui_out_table_header (struct ui_out *uiout, int width, enum ui_align alignment, const char *colhdr)

ui_out_table_header provides the header information for a single table column. You call this function several times, one each for every column of the table, after ui_out_table_begin, but before ui_out_table_body.

The value of width gives the column width in characters. The value of alignment is one of left, center, and right, and it specifies how to align the header: left-justify, center, or right-justify it. colhdr points to a string that specifies the column header; the implementation copies that string, so column header strings in malloced storage can be freed after the call.

Function: void ui_out_table_body (struct ui_out *uiout)

This function delimits the table header from the table body.

Function: void ui_out_table_end (struct ui_out *uiout)

This function signals the end of a table's output. It should be called after the table body has been produced by the list and field output functions.

There should be exactly one call to ui_out_table_end for each call to ui_out_table_begin, otherwise the ui_out functions will signal an internal error.

The output of the tuples that represent the table rows must follow the call to ui_out_table_body and precede the call to ui_out_table_end. You build a tuple by calling ui_out_tuple_begin and ui_out_tuple_end, with suitable calls to functions which actually output fields between them.

Function: void ui_out_tuple_begin (struct ui_out *uiout, const char *id)

This function marks the beginning of a tuple output. id points to an optional string that identifies the tuple; it is copied by the implementation, and so strings in malloced storage can be freed after the call.

Function: void ui_out_tuple_end (struct ui_out *uiout)

This function signals an end of a tuple output. There should be exactly one call to ui_out_tuple_end for each call to ui_out_tuple_begin, otherwise an internal GDB error will be signaled.

Function: struct cleanup *make_cleanup_ui_out_tuple_begin_end (struct ui_out *uiout, const char *id)

This function first opens the tuple and then establishes a cleanup (see section Cleanups) to close the tuple. It provides a convenient and correct implementation of the non-portable(1) code sequence:

struct cleanup *old_cleanup; ui_out_tuple_begin (uiout, "..."); old_cleanup = make_cleanup ((void(*)(void *)) ui_out_tuple_end, uiout);

Function: void ui_out_list_begin (struct ui_out *uiout, const char *id)

This function marks the beginning of a list output. id points to an optional string that identifies the list; it is copied by the implementation, and so strings in malloced storage can be freed after the call.

Function: void ui_out_list_end (struct ui_out *uiout)

This function signals an end of a list output. There should be exactly one call to ui_out_list_end for each call to ui_out_list_begin, otherwise an internal GDB error will be signaled.

Function: struct cleanup *make_cleanup_ui_out_list_begin_end (struct ui_out *uiout, const char *id)

Similar to make_cleanup_ui_out_tuple_begin_end, this function opens a list and then establishes cleanup (see section Cleanups) that will close the list.list.