lostecho/oldlinux-files
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
eec934fe6cdf00ff46c70c324c1949d18222ecc3
oldlinux-files/Ref-docs/manual gdb/gdbint/gdbint_4.html
gohigh ef50495c9d add directory Ref-docs
2024-02-19 00:21:47 -05:00

1012 lines
42 KiB
HTML
Raw Blame History

<HTML>
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<!-- Created on October, 18 2002 by texi2html 1.64 -->
<!--
Written by: Lionel Cons <Lionel.Cons@cern.ch> (original author)
Karl Berry <karl@freefriends.org>
Olaf Bachmann <obachman@mathematik.uni-kl.de>
and many others.
Maintained by: Olaf Bachmann <obachman@mathematik.uni-kl.de>
Send bugs and suggestions to <texi2html@mathematik.uni-kl.de>
-->
<HEAD>
<TITLE>GDB Internals: User Interface</TITLE>
<META NAME="description" CONTENT="GDB Internals: User Interface">
<META NAME="keywords" CONTENT="GDB Internals: User Interface">
<META NAME="resource-type" CONTENT="document">
<META NAME="distribution" CONTENT="global">
<META NAME="Generator" CONTENT="texi2html 1.64">
</HEAD>
<BODY LANG="" BGCOLOR="#FFFFFF" TEXT="#000000" LINK="#0000FF" VLINK="#800080" ALINK="#FF0000">
<A NAME="SEC16"></A>
<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdbint_3.html#SEC15"> &lt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdbint_4.html#SEC17"> &gt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdbint_5.html#SEC27"> &lt;&lt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdbint.html#SEC_Top"> Up </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdbint_5.html#SEC27"> &gt;&gt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdbint.html#SEC_Top">Top</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdbint_toc.html#SEC_Contents">Contents</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdbint_19.html#SEC186">Index</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdbint_abt.html#SEC_About"> ? </A>]</TD>
</TR></TABLE>
<H1> 4. User Interface </H1>
<!--docid::SEC16::-->
<P>
GDB has several user interfaces. Although the command-line interface
is the most common and most familiar, there are others.
</P><P>
<HR SIZE="6">
<A NAME="SEC17"></A>
<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdbint_4.html#SEC16"> &lt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdbint_4.html#SEC18"> &gt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdbint_4.html#SEC16"> &lt;&lt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdbint_4.html#SEC16"> Up </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdbint_5.html#SEC27"> &gt;&gt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdbint.html#SEC_Top">Top</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdbint_toc.html#SEC_Contents">Contents</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdbint_19.html#SEC186">Index</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdbint_abt.html#SEC_About"> ? </A>]</TD>
</TR></TABLE>
<H2> 4.1 Command Interpreter </H2>
<!--docid::SEC17::-->
<P>
<A NAME="IDX49"></A>
<A NAME="IDX50"></A>
The command interpreter in GDB is fairly simple. It is designed to
allow for the set of commands to be augmented dynamically, and also
has a recursive subcommand capability, where the first argument to
a command may itself direct a lookup on a different command list.
</P><P>
For instance, the <SAMP>`set'</SAMP> command just starts a lookup on the
<CODE>setlist</CODE> command list, while <SAMP>`set thread'</SAMP> recurses
to the <CODE>set_thread_cmd_list</CODE>.
</P><P>
<A NAME="IDX51"></A>
<A NAME="IDX52"></A>
To add commands in general, use <CODE>add_cmd</CODE>. <CODE>add_com</CODE> adds to
the main command list, and should be used for those commands. The usual
place to add commands is in the <CODE>_initialize_<VAR>xyz</VAR></CODE> routines at
the ends of most source files.
</P><P>
<A NAME="IDX53"></A>
<A NAME="IDX54"></A>
To add paired <SAMP>`set'</SAMP> and <SAMP>`show'</SAMP> commands, use
<CODE>add_setshow_cmd</CODE> or <CODE>add_setshow_cmd_full</CODE>. The former is
a slightly simpler interface which is useful when you don't need to
further modify the new command structures, while the latter returns
the new command structures for manipulation.
</P><P>
<A NAME="IDX55"></A>
<A NAME="IDX56"></A>
Before removing commands from the command set it is a good idea to
deprecate them for some time. Use <CODE>deprecate_cmd</CODE> on commands or
aliases to set the deprecated flag. <CODE>deprecate_cmd</CODE> takes a
<CODE>struct cmd_list_element</CODE> as it's first argument. You can use the
return value from <CODE>add_com</CODE> or <CODE>add_cmd</CODE> to deprecate the
command immediately after it is created.
</P><P>
The first time a command is used the user will be warned and offered a
replacement (if one exists). Note that the replacement string passed to
<CODE>deprecate_cmd</CODE> should be the full name of the command, i.e. the
entire string the user should type at the command line.
</P><P>
<HR SIZE="6">
<A NAME="SEC18"></A>
<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdbint_4.html#SEC17"> &lt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdbint_4.html#SEC19"> &gt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdbint_4.html#SEC25"> &lt;&lt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdbint_4.html#SEC16"> Up </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdbint_4.html#SEC25"> &gt;&gt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdbint.html#SEC_Top">Top</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdbint_toc.html#SEC_Contents">Contents</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdbint_19.html#SEC186">Index</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdbint_abt.html#SEC_About"> ? </A>]</TD>
</TR></TABLE>
<H2> 4.2 UI-Independent Output--the <CODE>ui_out</CODE> Functions </H2>
<!--docid::SEC18::-->
<P>
<A NAME="IDX57"></A>
The <CODE>ui_out</CODE> functions present an abstraction level for the
GDB output code. They hide the specifics of different user
interfaces supported by GDB, and thus free the programmer
from the need to write several versions of the same code, one each for
every UI, to produce output.
</P><P>
<HR SIZE="6">
<A NAME="SEC19"></A>
<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdbint_4.html#SEC18"> &lt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdbint_4.html#SEC20"> &gt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdbint_4.html#SEC25"> &lt;&lt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdbint_4.html#SEC18"> Up </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdbint_4.html#SEC25"> &gt;&gt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdbint.html#SEC_Top">Top</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdbint_toc.html#SEC_Contents">Contents</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdbint_19.html#SEC186">Index</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdbint_abt.html#SEC_About"> ? </A>]</TD>
</TR></TABLE>
<H3> 4.2.1 Overview and Terminology </H3>
<!--docid::SEC19::-->
<P>
In general, execution of each GDB command produces some sort
of output, and can even generate an input request.
</P><P>
Output can be generated for the following purposes:
</P><P>
<UL>
<LI>
to display a <EM>result</EM> of an operation;
<P>
<LI>
to convey <EM>info</EM> or produce side-effects of a requested
operation;
<P>
<LI>
to provide a <EM>notification</EM> of an asynchronous event (including
progress indication of a prolonged asynchronous operation);
<P>
<LI>
to display <EM>error messages</EM> (including warnings);
<P>
<LI>
to show <EM>debug data</EM>;
<P>
<LI>
to <EM>query</EM> or prompt a user for input (a special case).
</UL>
<P>
This section mainly concentrates on how to build result output,
although some of it also applies to other kinds of output.
</P><P>
Generation of output that displays the results of an operation
involves one or more of the following:
</P><P>
<UL>
<LI>
output of the actual data
<P>
<LI>
formatting the output as appropriate for console output, to make it
easily readable by humans
<P>
<LI>
machine oriented formatting--a more terse formatting to allow for easy
parsing by programs which read GDB's output
<P>
<LI>
annotation, whose purpose is to help legacy GUIs to identify interesting
parts in the output
</UL>
<P>
The <CODE>ui_out</CODE> routines take care of the first three aspects.
Annotations are provided by separate annotation routines. Note that use
of annotations for an interface between a GUI and GDB is
deprecated.
</P><P>
Output can be in the form of a single item, which we call a <EM>field</EM>;
a <EM>list</EM> consisting of identical fields; a <EM>tuple</EM> consisting of
non-identical fields; or a <EM>table</EM>, which is a tuple consisting of a
header and a body. In a BNF-like form:
</P><P>
<DL COMPACT>
<DT><CODE>&#60;table&#62; ==></CODE>
<DD><CODE>&#60;header&#62; &#60;body&#62;</CODE>
<DT><CODE>&#60;header&#62; ==></CODE>
<DD><CODE>{ &#60;column&#62; }</CODE>
<DT><CODE>&#60;column&#62; ==></CODE>
<DD><CODE>&#60;width&#62; &#60;alignment&#62; &#60;title&#62;</CODE>
<DT><CODE>&#60;body&#62; ==></CODE>
<DD><CODE>{&#60;row&#62;}</CODE>
</DL>
<P>
<HR SIZE="6">
<A NAME="SEC20"></A>
<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdbint_4.html#SEC19"> &lt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdbint_4.html#SEC21"> &gt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdbint_4.html#SEC21"> &lt;&lt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdbint_4.html#SEC18"> Up </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdbint_4.html#SEC25"> &gt;&gt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdbint.html#SEC_Top">Top</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdbint_toc.html#SEC_Contents">Contents</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdbint_19.html#SEC186">Index</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdbint_abt.html#SEC_About"> ? </A>]</TD>
</TR></TABLE>
<H3> 4.2.2 General Conventions </H3>
<!--docid::SEC20::-->
<P>
Most <CODE>ui_out</CODE> routines are of type <CODE>void</CODE>, the exceptions are
<CODE>ui_out_stream_new</CODE> (which returns a pointer to the newly created
object) and the <CODE>make_cleanup</CODE> routines.
</P><P>
The first parameter is always the <CODE>ui_out</CODE> vector object, a pointer
to a <CODE>struct ui_out</CODE>.
</P><P>
The <VAR>format</VAR> parameter is like in <CODE>printf</CODE> family of functions.
When it is present, there must also be a variable list of arguments
sufficient used to satisfy the <CODE>%</CODE> specifiers in the supplied
format.
</P><P>
When a character string argument is not used in a <CODE>ui_out</CODE> function
call, a <CODE>NULL</CODE> pointer has to be supplied instead.
</P><P>
<HR SIZE="6">
<A NAME="SEC21"></A>
<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdbint_4.html#SEC20"> &lt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdbint_4.html#SEC22"> &gt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdbint_4.html#SEC22"> &lt;&lt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdbint_4.html#SEC18"> Up </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdbint_4.html#SEC25"> &gt;&gt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdbint.html#SEC_Top">Top</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdbint_toc.html#SEC_Contents">Contents</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdbint_19.html#SEC186">Index</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdbint_abt.html#SEC_About"> ? </A>]</TD>
</TR></TABLE>
<H3> 4.2.3 Table, Tuple and List Functions </H3>
<!--docid::SEC21::-->
<P>
<A NAME="IDX58"></A>
<A NAME="IDX59"></A>
<A NAME="IDX60"></A>
This section introduces <CODE>ui_out</CODE> routines for building lists,
tuples and tables. The routines to output the actual data items
(fields) are presented in the next section.
</P><P>
To recap: A <EM>tuple</EM> is a sequence of <EM>fields</EM>, each field
containing information about an object; a <EM>list</EM> is a sequence of
fields where each field describes an identical object.
</P><P>
Use the <EM>table</EM> 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.
</P><P>
<A NAME="IDX61"></A>
Tables can not be nested. Tuples and lists can be nested up to a
maximum of five levels.
</P><P>
The overall structure of the table output code is something like this:
</P><P>
<TABLE><tr><td>&nbsp;</td><td class=smallexample><FONT SIZE=-1><pre> ui_out_table_begin
ui_out_table_header
<small>...</small>
ui_out_table_body
ui_out_tuple_begin
ui_out_field_*
<small>...</small>
ui_out_tuple_end
<small>...</small>
ui_out_table_end
</FONT></pre></td></tr></table></P><P>
Here is the description of table-, tuple- and list-related <CODE>ui_out</CODE>
functions:
</P><P>
<A NAME="IDX62"></A>
<DL>
<DT><U>Function:</U> void <B>ui_out_table_begin</B> <I>(struct ui_out *<VAR>uiout</VAR>, int <VAR>nbrofcols</VAR>, int <VAR>nr_rows</VAR>, const char *<VAR>tblid</VAR>)</I>
<DD>The function <CODE>ui_out_table_begin</CODE> marks the beginning of the output
of a table. It should always be called before any other <CODE>ui_out</CODE>
function for a given table. <VAR>nbrofcols</VAR> is the number of columns in
the table. <VAR>nr_rows</VAR> is the number of rows in the table.
<VAR>tblid</VAR> is an optional string identifying the table. The string
pointed to by <VAR>tblid</VAR> is copied by the implementation of
<CODE>ui_out_table_begin</CODE>, so the application can free the string if it
was <CODE>malloc</CODE>ed.
</P><P>
The companion function <CODE>ui_out_table_end</CODE>, described below, marks
the end of the table's output.
</DL>
</P><P>
<A NAME="IDX63"></A>
<DL>
<DT><U>Function:</U> void <B>ui_out_table_header</B> <I>(struct ui_out *<VAR>uiout</VAR>, int <VAR>width</VAR>, enum ui_align <VAR>alignment</VAR>, const char *<VAR>colhdr</VAR>)</I>
<DD><CODE>ui_out_table_header</CODE> provides the header information for a single
table column. You call this function several times, one each for every
column of the table, after <CODE>ui_out_table_begin</CODE>, but before
<CODE>ui_out_table_body</CODE>.
</P><P>
The value of <VAR>width</VAR> gives the column width in characters. The
value of <VAR>alignment</VAR> is one of <CODE>left</CODE>, <CODE>center</CODE>, and
<CODE>right</CODE>, and it specifies how to align the header: left-justify,
center, or right-justify it. <VAR>colhdr</VAR> points to a string that
specifies the column header; the implementation copies that string, so
column header strings in <CODE>malloc</CODE>ed storage can be freed after the
call.
</DL>
</P><P>
<A NAME="IDX64"></A>
<DL>
<DT><U>Function:</U> void <B>ui_out_table_body</B> <I>(struct ui_out *<VAR>uiout</VAR>)</I>
<DD>This function delimits the table header from the table body.
</DL>
</P><P>
<A NAME="IDX65"></A>
<DL>
<DT><U>Function:</U> void <B>ui_out_table_end</B> <I>(struct ui_out *<VAR>uiout</VAR>)</I>
<DD>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.
</P><P>
There should be exactly one call to <CODE>ui_out_table_end</CODE> for each
call to <CODE>ui_out_table_begin</CODE>, otherwise the <CODE>ui_out</CODE> functions
will signal an internal error.
</DL>
</P><P>
The output of the tuples that represent the table rows must follow the
call to <CODE>ui_out_table_body</CODE> and precede the call to
<CODE>ui_out_table_end</CODE>. You build a tuple by calling
<CODE>ui_out_tuple_begin</CODE> and <CODE>ui_out_tuple_end</CODE>, with suitable
calls to functions which actually output fields between them.
</P><P>
<A NAME="IDX66"></A>
<DL>
<DT><U>Function:</U> void <B>ui_out_tuple_begin</B> <I>(struct ui_out *<VAR>uiout</VAR>, const char *<VAR>id</VAR>)</I>
<DD>This function marks the beginning of a tuple output. <VAR>id</VAR> points
to an optional string that identifies the tuple; it is copied by the
implementation, and so strings in <CODE>malloc</CODE>ed storage can be freed
after the call.
</DL>
</P><P>
<A NAME="IDX67"></A>
<DL>
<DT><U>Function:</U> void <B>ui_out_tuple_end</B> <I>(struct ui_out *<VAR>uiout</VAR>)</I>
<DD>This function signals an end of a tuple output. There should be exactly
one call to <CODE>ui_out_tuple_end</CODE> for each call to
<CODE>ui_out_tuple_begin</CODE>, otherwise an internal GDB error will
be signaled.
</DL>
</P><P>
<A NAME="IDX68"></A>
<DL>
<DT><U>Function:</U> struct <B>cleanup</B> <I>*make_cleanup_ui_out_tuple_begin_end (struct ui_out *<VAR>uiout</VAR>, const char *<VAR>id</VAR>)</I>
<DD>This function first opens the tuple and then establishes a cleanup
(see section <A HREF="gdbint_13.html#SEC110">Cleanups</A>) to close the tuple. It provides a convenient
and correct implementation of the non-portable<A NAME="DOCF1" HREF="gdbint_fot.html#FOOT1">(1)</A> code sequence:
<TABLE><tr><td>&nbsp;</td><td class=smallexample><FONT SIZE=-1><pre>struct cleanup *old_cleanup;
ui_out_tuple_begin (uiout, "...");
old_cleanup = make_cleanup ((void(*)(void *)) ui_out_tuple_end,
uiout);
</FONT></pre></td></tr></table></DL>
</P><P>
<A NAME="IDX69"></A>
<DL>
<DT><U>Function:</U> void <B>ui_out_list_begin</B> <I>(struct ui_out *<VAR>uiout</VAR>, const char *<VAR>id</VAR>)</I>
<DD>This function marks the beginning of a list output. <VAR>id</VAR> points to
an optional string that identifies the list; it is copied by the
implementation, and so strings in <CODE>malloc</CODE>ed storage can be freed
after the call.
</DL>
</P><P>
<A NAME="IDX70"></A>
<DL>
<DT><U>Function:</U> void <B>ui_out_list_end</B> <I>(struct ui_out *<VAR>uiout</VAR>)</I>
<DD>This function signals an end of a list output. There should be exactly
one call to <CODE>ui_out_list_end</CODE> for each call to
<CODE>ui_out_list_begin</CODE>, otherwise an internal GDB error will
be signaled.
</DL>
</P><P>
<A NAME="IDX71"></A>
<DL>
<DT><U>Function:</U> struct <B>cleanup</B> <I>*make_cleanup_ui_out_list_begin_end (struct ui_out *<VAR>uiout</VAR>, const char *<VAR>id</VAR>)</I>
<DD>Similar to <CODE>make_cleanup_ui_out_tuple_begin_end</CODE>, this function
opens a list and then establishes cleanup (see section <A HREF="gdbint_13.html#SEC110">Cleanups</A>)
that will close the list.list.
</DL>
</P><P>
<HR SIZE="6">
<A NAME="SEC22"></A>
<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdbint_4.html#SEC21"> &lt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdbint_4.html#SEC23"> &gt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdbint_4.html#SEC23"> &lt;&lt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdbint_4.html#SEC18"> Up </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdbint_4.html#SEC25"> &gt;&gt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdbint.html#SEC_Top">Top</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdbint_toc.html#SEC_Contents">Contents</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdbint_19.html#SEC186">Index</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdbint_abt.html#SEC_About"> ? </A>]</TD>
</TR></TABLE>
<H3> 4.2.4 Item Output Functions </H3>
<!--docid::SEC22::-->
<P>
<A NAME="IDX72"></A>
<A NAME="IDX73"></A>
<A NAME="IDX74"></A>
The functions described below produce output for the actual data
items, or fields, which contain information about the object.
</P><P>
Choose the appropriate function accordingly to your particular needs.
</P><P>
<A NAME="IDX75"></A>
<DL>
<DT><U>Function:</U> void <B>ui_out_field_fmt</B> <I>(struct ui_out *<VAR>uiout</VAR>, char *<VAR>fldname</VAR>, char *<VAR>format</VAR>, ...)</I>
<DD>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 <VAR>format</VAR>, a
<CODE>printf</CODE>-like format string. The optional argument <VAR>fldname</VAR>
supplies the name of the field. The data items themselves are
supplied as additional arguments after <VAR>format</VAR>.
</P><P>
This generic function should be used only when it is not possible to
use one of the specialized versions (see below).
</DL>
</P><P>
<A NAME="IDX76"></A>
<DL>
<DT><U>Function:</U> void <B>ui_out_field_int</B> <I>(struct ui_out *<VAR>uiout</VAR>, const char *<VAR>fldname</VAR>, int <VAR>value</VAR>)</I>
<DD>This function outputs a value of an <CODE>int</CODE> variable. It uses the
<CODE>"%d"</CODE> output conversion specification. <VAR>fldname</VAR> specifies
the name of the field.
</DL>
</P><P>
<A NAME="IDX77"></A>
<DL>
<DT><U>Function:</U> void <B>ui_out_field_fmt_int</B> <I>(struct ui_out *<VAR>uiout</VAR>, int <VAR>width</VAR>, enum ui_align <VAR>alignment</VAR>, const char *<VAR>fldname</VAR>, int <VAR>value</VAR>)</I>
<DD>This function outputs a value of an <CODE>int</CODE> variable. It differs from
<CODE>ui_out_field_int</CODE> in that the caller specifies the desired <VAR>width</VAR> and <VAR>alignment</VAR> of the output.
<VAR>fldname</VAR> specifies
the name of the field.
</DL>
</P><P>
<A NAME="IDX78"></A>
<DL>
<DT><U>Function:</U> void <B>ui_out_field_core_addr</B> <I>(struct ui_out *<VAR>uiout</VAR>, const char *<VAR>fldname</VAR>, CORE_ADDR <VAR>address</VAR>)</I>
<DD>This function outputs an address.
</DL>
</P><P>
<A NAME="IDX79"></A>
<DL>
<DT><U>Function:</U> void <B>ui_out_field_string</B> <I>(struct ui_out *<VAR>uiout</VAR>, const char *<VAR>fldname</VAR>, const char *<VAR>string</VAR>)</I>
<DD>This function outputs a string using the <CODE>"%s"</CODE> conversion
specification.
</DL>
</P><P>
Sometimes, there's a need to compose your output piece by piece using
functions that operate on a stream, such as <CODE>value_print</CODE> or
<CODE>fprintf_symbol_filtered</CODE>. These functions accept an argument of
the type <CODE>struct ui_file *</CODE>, a pointer to a <CODE>ui_file</CODE> 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
<CODE>ui_file</CODE> object to the <CODE>ui_out</CODE> functions. To this end,
you first create a <CODE>ui_stream</CODE> object by calling
<CODE>ui_out_stream_new</CODE>, pass the <CODE>stream</CODE> member of that
<CODE>ui_stream</CODE> object to <CODE>value_print</CODE> and similar functions,
and finally call <CODE>ui_out_field_stream</CODE> to output the field you
constructed. When the <CODE>ui_stream</CODE> object is no longer needed,
you should destroy it and free its memory by calling
<CODE>ui_out_stream_delete</CODE>.
</P><P>
<A NAME="IDX80"></A>
<DL>
<DT><U>Function:</U> struct <B>ui_stream</B> <I>*ui_out_stream_new (struct ui_out *<VAR>uiout</VAR>)</I>
<DD>This function creates a new <CODE>ui_stream</CODE> object which uses the
same output methods as the <CODE>ui_out</CODE> object whose pointer is
passed in <VAR>uiout</VAR>. It returns a pointer to the newly created
<CODE>ui_stream</CODE> object.
</DL>
</P><P>
<A NAME="IDX81"></A>
<DL>
<DT><U>Function:</U> void <B>ui_out_stream_delete</B> <I>(struct ui_stream *<VAR>streambuf</VAR>)</I>
<DD>This functions destroys a <CODE>ui_stream</CODE> object specified by
<VAR>streambuf</VAR>.
</DL>
</P><P>
<A NAME="IDX82"></A>
<DL>
<DT><U>Function:</U> void <B>ui_out_field_stream</B> <I>(struct ui_out *<VAR>uiout</VAR>, const char *<VAR>fieldname</VAR>, struct ui_stream *<VAR>streambuf</VAR>)</I>
<DD>This function consumes all the data accumulated in
<CODE>streambuf-&#62;stream</CODE> and outputs it like
<CODE>ui_out_field_string</CODE> does. After a call to
<CODE>ui_out_field_stream</CODE>, the accumulated data no longer exists, but
the stream is still valid and may be used for producing more fields.
</DL>
</P><P>
<STRONG>Important:</STRONG> If there is any chance that your code could bail
out before completing output generation and reaching the point where
<CODE>ui_out_stream_delete</CODE> 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:
</P><P>
<TABLE><tr><td>&nbsp;</td><td class=smallexample><FONT SIZE=-1><pre> struct ui_stream *mybuf = ui_out_stream_new (uiout);
struct cleanup *old = make_cleanup (ui_out_stream_delete, mybuf);
...
do_cleanups (old);
</FONT></pre></td></tr></table></P><P>
If the function already has the old cleanup chain set (for other kinds
of cleanups), you just have to add your cleanup to it:
</P><P>
<TABLE><tr><td>&nbsp;</td><td class=smallexample><FONT SIZE=-1><pre> mybuf = ui_out_stream_new (uiout);
make_cleanup (ui_out_stream_delete, mybuf);
</FONT></pre></td></tr></table></P><P>
Note that with cleanups in place, you should not call
<CODE>ui_out_stream_delete</CODE> directly, or you would attempt to free the
same buffer twice.
</P><P>
<HR SIZE="6">
<A NAME="SEC23"></A>
<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdbint_4.html#SEC22"> &lt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdbint_4.html#SEC24"> &gt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdbint_4.html#SEC24"> &lt;&lt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdbint_4.html#SEC18"> Up </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdbint_4.html#SEC25"> &gt;&gt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdbint.html#SEC_Top">Top</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdbint_toc.html#SEC_Contents">Contents</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdbint_19.html#SEC186">Index</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdbint_abt.html#SEC_About"> ? </A>]</TD>
</TR></TABLE>
<H3> 4.2.5 Utility Output Functions </H3>
<!--docid::SEC23::-->
<P>
<A NAME="IDX83"></A>
<DL>
<DT><U>Function:</U> void <B>ui_out_field_skip</B> <I>(struct ui_out *<VAR>uiout</VAR>, const char *<VAR>fldname</VAR>)</I>
<DD>This function skips a field in a table. Use it if you have to leave
an empty field without disrupting the table alignment. The argument
<VAR>fldname</VAR> specifies a name for the (missing) filed.
</DL>
</P><P>
<A NAME="IDX84"></A>
<DL>
<DT><U>Function:</U> void <B>ui_out_text</B> <I>(struct ui_out *<VAR>uiout</VAR>, const char *<VAR>string</VAR>)</I>
<DD>This function outputs the text in <VAR>string</VAR> in a way that makes it
easy to be read by humans. For example, the console implementation of
this method filters the text through a built-in pager, to prevent it
from scrolling off the visible portion of the screen.
</P><P>
Use this function for printing relatively long chunks of text around
the actual field data: the text it produces is not aligned according
to the table's format. Use <CODE>ui_out_field_string</CODE> to output a
string field, and use <CODE>ui_out_message</CODE>, described below, to
output short messages.
</DL>
</P><P>
<A NAME="IDX85"></A>
<DL>
<DT><U>Function:</U> void <B>ui_out_spaces</B> <I>(struct ui_out *<VAR>uiout</VAR>, int <VAR>nspaces</VAR>)</I>
<DD>This function outputs <VAR>nspaces</VAR> spaces. It is handy to align the
text produced by <CODE>ui_out_text</CODE> with the rest of the table or
list.
</DL>
</P><P>
<A NAME="IDX86"></A>
<DL>
<DT><U>Function:</U> void <B>ui_out_message</B> <I>(struct ui_out *<VAR>uiout</VAR>, int <VAR>verbosity</VAR>, const char *<VAR>format</VAR>, ...)</I>
<DD>This function produces a formatted message, provided that the current
verbosity level is at least as large as given by <VAR>verbosity</VAR>. The
current verbosity level is specified by the user with the <SAMP>`set
verbositylevel'</SAMP> command.<A NAME="DOCF2" HREF="gdbint_fot.html#FOOT2">(2)</A>
</DL>
</P><P>
<A NAME="IDX87"></A>
<DL>
<DT><U>Function:</U> void <B>ui_out_wrap_hint</B> <I>(struct ui_out *<VAR>uiout</VAR>, char *<VAR>indent</VAR>)</I>
<DD>This function gives the console output filter (a paging filter) a hint
of where to break lines which are too long. Ignored for all other
output consumers. <VAR>indent</VAR>, if non-<CODE>NULL</CODE>, is the string to
be printed to indent the wrapped text on the next line; it must remain
accessible until the next call to <CODE>ui_out_wrap_hint</CODE>, or until an
explicit newline is produced by one of the other functions. If
<VAR>indent</VAR> is <CODE>NULL</CODE>, the wrapped text will not be indented.
</DL>
</P><P>
<A NAME="IDX88"></A>
<DL>
<DT><U>Function:</U> void <B>ui_out_flush</B> <I>(struct ui_out *<VAR>uiout</VAR>)</I>
<DD>This function flushes whatever output has been accumulated so far, if
the UI buffers output.
</DL>
</P><P>
<HR SIZE="6">
<A NAME="SEC24"></A>
<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdbint_4.html#SEC23"> &lt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdbint_4.html#SEC25"> &gt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdbint_4.html#SEC25"> &lt;&lt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdbint_4.html#SEC18"> Up </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdbint_4.html#SEC25"> &gt;&gt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdbint.html#SEC_Top">Top</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdbint_toc.html#SEC_Contents">Contents</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdbint_19.html#SEC186">Index</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdbint_abt.html#SEC_About"> ? </A>]</TD>
</TR></TABLE>
<H3> 4.2.6 Examples of Use of <CODE>ui_out</CODE> functions </H3>
<!--docid::SEC24::-->
<P>
<A NAME="IDX89"></A>
<A NAME="IDX90"></A>
This section gives some practical examples of using the <CODE>ui_out</CODE>
functions to generalize the old console-oriented code in
GDB. The examples all come from functions defined on the
<TT>`breakpoints.c'</TT> file.
</P><P>
This example, from the <CODE>breakpoint_1</CODE> function, shows how to
produce a table.
</P><P>
The original code was:
</P><P>
<TABLE><tr><td>&nbsp;</td><td class=smallexample><FONT SIZE=-1><pre> if (!found_a_breakpoint++)
{
annotate_breakpoints_headers ();
annotate_field (0);
printf_filtered ("Num ");
annotate_field (1);
printf_filtered ("Type ");
annotate_field (2);
printf_filtered ("Disp ");
annotate_field (3);
printf_filtered ("Enb ");
if (addressprint)
{
annotate_field (4);
printf_filtered ("Address ");
}
annotate_field (5);
printf_filtered ("What\n");
annotate_breakpoints_table ();
}
</FONT></pre></td></tr></table></P><P>
Here's the new version:
</P><P>
<TABLE><tr><td>&nbsp;</td><td class=smallexample><FONT SIZE=-1><pre> nr_printable_breakpoints = <small>...</small>;
if (addressprint)
ui_out_table_begin (ui, 6, nr_printable_breakpoints, "BreakpointTable");
else
ui_out_table_begin (ui, 5, nr_printable_breakpoints, "BreakpointTable");
if (nr_printable_breakpoints &#62; 0)
annotate_breakpoints_headers ();
if (nr_printable_breakpoints &#62; 0)
annotate_field (0);
ui_out_table_header (uiout, 3, ui_left, "number", "Num"); /* 1 */
if (nr_printable_breakpoints &#62; 0)
annotate_field (1);
ui_out_table_header (uiout, 14, ui_left, "type", "Type"); /* 2 */
if (nr_printable_breakpoints &#62; 0)
annotate_field (2);
ui_out_table_header (uiout, 4, ui_left, "disp", "Disp"); /* 3 */
if (nr_printable_breakpoints &#62; 0)
annotate_field (3);
ui_out_table_header (uiout, 3, ui_left, "enabled", "Enb"); /* 4 */
if (addressprint)
{
if (nr_printable_breakpoints &#62; 0)
annotate_field (4);
if (TARGET_ADDR_BIT &#60;= 32)
ui_out_table_header (uiout, 10, ui_left, "addr", "Address");/* 5 */
else
ui_out_table_header (uiout, 18, ui_left, "addr", "Address");/* 5 */
}
if (nr_printable_breakpoints &#62; 0)
annotate_field (5);
ui_out_table_header (uiout, 40, ui_noalign, "what", "What"); /* 6 */
ui_out_table_body (uiout);
if (nr_printable_breakpoints &#62; 0)
annotate_breakpoints_table ();
</FONT></pre></td></tr></table></P><P>
This example, from the <CODE>print_one_breakpoint</CODE> function, shows how
to produce the actual data for the table whose structure was defined
in the above example. The original code was:
</P><P>
<TABLE><tr><td>&nbsp;</td><td class=smallexample><FONT SIZE=-1><pre> annotate_record ();
annotate_field (0);
printf_filtered ("%-3d ", b-&#62;number);
annotate_field (1);
if ((int)b-&#62;type &#62; (sizeof(bptypes)/sizeof(bptypes[0]))
|| ((int) b-&#62;type != bptypes[(int) b-&#62;type].type))
internal_error ("bptypes table does not describe type #%d.",
(int)b-&#62;type);
printf_filtered ("%-14s ", bptypes[(int)b-&#62;type].description);
annotate_field (2);
printf_filtered ("%-4s ", bpdisps[(int)b-&#62;disposition]);
annotate_field (3);
printf_filtered ("%-3c ", bpenables[(int)b-&#62;enable]);
<small>...</small>
</FONT></pre></td></tr></table></P><P>
This is the new version:
</P><P>
<TABLE><tr><td>&nbsp;</td><td class=smallexample><FONT SIZE=-1><pre> annotate_record ();
ui_out_tuple_begin (uiout, "bkpt");
annotate_field (0);
ui_out_field_int (uiout, "number", b-&#62;number);
annotate_field (1);
if (((int) b-&#62;type &#62; (sizeof (bptypes) / sizeof (bptypes[0])))
|| ((int) b-&#62;type != bptypes[(int) b-&#62;type].type))
internal_error ("bptypes table does not describe type #%d.",
(int) b-&#62;type);
ui_out_field_string (uiout, "type", bptypes[(int)b-&#62;type].description);
annotate_field (2);
ui_out_field_string (uiout, "disp", bpdisps[(int)b-&#62;disposition]);
annotate_field (3);
ui_out_field_fmt (uiout, "enabled", "%c", bpenables[(int)b-&#62;enable]);
<small>...</small>
</FONT></pre></td></tr></table></P><P>
This example, also from <CODE>print_one_breakpoint</CODE>, shows how to
produce a complicated output field using the <CODE>print_expression</CODE>
functions which requires a stream to be passed. It also shows how to
automate stream destruction with cleanups. The original code was:
</P><P>
<TABLE><tr><td>&nbsp;</td><td class=smallexample><FONT SIZE=-1><pre> annotate_field (5);
print_expression (b-&#62;exp, gdb_stdout);
</FONT></pre></td></tr></table></P><P>
The new version is:
</P><P>
<TABLE><tr><td>&nbsp;</td><td class=smallexample><FONT SIZE=-1><pre> struct ui_stream *stb = ui_out_stream_new (uiout);
struct cleanup *old_chain = make_cleanup_ui_out_stream_delete (stb);
...
annotate_field (5);
print_expression (b-&#62;exp, stb-&#62;stream);
ui_out_field_stream (uiout, "what", local_stream);
</FONT></pre></td></tr></table></P><P>
This example, also from <CODE>print_one_breakpoint</CODE>, shows how to use
<CODE>ui_out_text</CODE> and <CODE>ui_out_field_string</CODE>. The original code
was:
</P><P>
<TABLE><tr><td>&nbsp;</td><td class=smallexample><FONT SIZE=-1><pre> annotate_field (5);
if (b-&#62;dll_pathname == NULL)
printf_filtered ("&#60;any library&#62; ");
else
printf_filtered ("library \"%s\" ", b-&#62;dll_pathname);
</FONT></pre></td></tr></table></P><P>
It became:
</P><P>
<TABLE><tr><td>&nbsp;</td><td class=smallexample><FONT SIZE=-1><pre> annotate_field (5);
if (b-&#62;dll_pathname == NULL)
{
ui_out_field_string (uiout, "what", "<any library>");
ui_out_spaces (uiout, 1);
}
else
{
ui_out_text (uiout, "library \"");
ui_out_field_string (uiout, "what", b-&#62;dll_pathname);
ui_out_text (uiout, "\" ");
}
</FONT></pre></td></tr></table></P><P>
The following example from <CODE>print_one_breakpoint</CODE> shows how to
use <CODE>ui_out_field_int</CODE> and <CODE>ui_out_spaces</CODE>. The original
code was:
</P><P>
<TABLE><tr><td>&nbsp;</td><td class=smallexample><FONT SIZE=-1><pre> annotate_field (5);
if (b-&#62;forked_inferior_pid != 0)
printf_filtered ("process %d ", b-&#62;forked_inferior_pid);
</FONT></pre></td></tr></table></P><P>
It became:
</P><P>
<TABLE><tr><td>&nbsp;</td><td class=smallexample><FONT SIZE=-1><pre> annotate_field (5);
if (b-&#62;forked_inferior_pid != 0)
{
ui_out_text (uiout, "process ");
ui_out_field_int (uiout, "what", b-&#62;forked_inferior_pid);
ui_out_spaces (uiout, 1);
}
</FONT></pre></td></tr></table></P><P>
Here's an example of using <CODE>ui_out_field_string</CODE>. The original
code was:
</P><P>
<TABLE><tr><td>&nbsp;</td><td class=smallexample><FONT SIZE=-1><pre> annotate_field (5);
if (b-&#62;exec_pathname != NULL)
printf_filtered ("program \"%s\" ", b-&#62;exec_pathname);
</FONT></pre></td></tr></table></P><P>
It became:
</P><P>
<TABLE><tr><td>&nbsp;</td><td class=smallexample><FONT SIZE=-1><pre> annotate_field (5);
if (b-&#62;exec_pathname != NULL)
{
ui_out_text (uiout, "program \"");
ui_out_field_string (uiout, "what", b-&#62;exec_pathname);
ui_out_text (uiout, "\" ");
}
</FONT></pre></td></tr></table></P><P>
Finally, here's an example of printing an address. The original code:
</P><P>
<TABLE><tr><td>&nbsp;</td><td class=smallexample><FONT SIZE=-1><pre> annotate_field (4);
printf_filtered ("%s ",
local_hex_string_custom ((unsigned long) b-&#62;address, "08l"));
</FONT></pre></td></tr></table></P><P>
It became:
</P><P>
<TABLE><tr><td>&nbsp;</td><td class=smallexample><FONT SIZE=-1><pre> annotate_field (4);
ui_out_field_core_addr (uiout, "Address", b-&#62;address);
</FONT></pre></td></tr></table></P><P>
<HR SIZE="6">
<A NAME="SEC25"></A>
<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdbint_4.html#SEC24"> &lt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdbint_4.html#SEC26"> &gt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdbint_4.html#SEC26"> &lt;&lt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdbint_4.html#SEC16"> Up </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdbint_5.html#SEC27"> &gt;&gt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdbint.html#SEC_Top">Top</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdbint_toc.html#SEC_Contents">Contents</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdbint_19.html#SEC186">Index</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdbint_abt.html#SEC_About"> ? </A>]</TD>
</TR></TABLE>
<H2> 4.3 Console Printing </H2>
<!--docid::SEC25::-->
<P>
<HR SIZE="6">
<A NAME="SEC26"></A>
<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdbint_4.html#SEC25"> &lt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdbint_5.html#SEC27"> &gt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdbint_4.html#SEC16"> &lt;&lt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdbint_4.html#SEC16"> Up </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdbint_5.html#SEC27"> &gt;&gt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdbint.html#SEC_Top">Top</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdbint_toc.html#SEC_Contents">Contents</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdbint_19.html#SEC186">Index</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdbint_abt.html#SEC_About"> ? </A>]</TD>
</TR></TABLE>
<H2> 4.4 TUI </H2>
<!--docid::SEC26::-->
<P>
<A NAME="libgdb"></A>
</P><P>
<HR SIZE="6">
<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdbint_4.html#SEC16"> &lt;&lt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdbint_5.html#SEC27"> &gt;&gt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdbint.html#SEC_Top">Top</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdbint_toc.html#SEC_Contents">Contents</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdbint_19.html#SEC186">Index</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdbint_abt.html#SEC_About"> ? </A>]</TD>
</TR></TABLE>
<BR>
<FONT SIZE="-1">
<address>
<p>Please send FSF &amp; GNU inquiries &amp; questions to <a
href="mailto:gnu@gnu.org">gnu@gnu.org</a>. There are also <a
href="http://www.gnu.org/home.html#ContactInfo">other ways to
contact</a> the FSF.</p>
<p>These pages are maintained by <a
href="http://www.gnu.org/software/gdb/">the GDB developers</a>.</p>
<p>Copyright Free Software Foundation, Inc., 59 Temple Place - Suite
330, Boston, MA 02111, USA.</p>
<p>Verbatim copying and distribution of this entire article is
permitted in any medium, provided this notice is preserved.</p>
</address>
This document was generated
by <I>GDB Administrator</I> on <I>October, 18 2002</I>
using <A HREF="http://www.mathematik.uni-kl.de/~obachman/Texi2html
"><I>texi2html</I></A>
</BODY>
</HTML>
Reference in New Issue View Git Blame Copy Permalink