mingw/info/gdbint/User-Interface.html

   1 <html lang="en">
   2 <head>
   3 <title>GDB Internals</title>
   4 <meta http-equiv="Content-Type" content="text/html">
   5 <meta name="description" content="GDB Internals">
   6 <meta name="generator" content="makeinfo 4.3">
   7 <link href="http://www.gnu.org/software/texinfo/" rel="generator-home">
   8 </head>
   9 <body>
  10 <div class="node">
  11 <p>
  12 Node:<a name="User%20Interface">User Interface</a>,
  13 Next:<a rel="next" accesskey="n" href="libgdb.html#libgdb">libgdb</a>,
  14 Previous:<a rel="previous" accesskey="p" href="Algorithms.html#Algorithms">Algorithms</a>,
  15 Up:<a rel="up" accesskey="u" href="index.html#Top">Top</a>
  16 <hr><br>
  17 </div>
  18
  19 <h2 class="chapter">User Interface</h2>
  20
  21    GDB has several user interfaces.  Although the command-line interface
  22 is the most common and most familiar, there are others.
  23
  24 <h3 class="section">Command Interpreter</h3>
  25
  26    <p>The command interpreter in GDB is fairly simple.  It is designed to
  27 allow for the set of commands to be augmented dynamically, and also
  28 has a recursive subcommand capability, where the first argument to
  29 a command may itself direct a lookup on a different command list.
  30
  31    <p>For instance, the <code>set</code> command just starts a lookup on the
  32 <code>setlist</code> command list, while <code>set thread</code> recurses
  33 to the <code>set_thread_cmd_list</code>.
  34
  35    <p>To add commands in general, use <code>add_cmd</code>.  <code>add_com</code> adds to
  36 the main command list, and should be used for those commands.  The usual
  37 place to add commands is in the <code>_initialize_</code><var>xyz</var><code></code> routines at
  38 the ends of most source files.
  39
  40    <p>Before removing commands from the command set it is a good idea to
  41 deprecate them for some time.  Use <code>deprecate_cmd</code> on commands or
  42 aliases to set the deprecated flag.  <code>deprecate_cmd</code> takes a
  43 <code>struct cmd_list_element</code> as it's first argument.  You can use the
  44 return value from <code>add_com</code> or <code>add_cmd</code> to deprecate the
  45 command immediately after it is created.
  46
  47    <p>The first time a command is used the user will be warned and offered a
  48 replacement (if one exists). Note that the replacement string passed to
  49 <code>deprecate_cmd</code> should be the full name of the command, i.e. the
  50 entire string the user should type at the command line.
  51
  52 <h3 class="section">UI-Independent Output--the <code>ui_out</code> Functions</h3>
  53
  54    <p>The <code>ui_out</code> functions present an abstraction level for the
  55 GDB output code.  They hide the specifics of different user
  56 interfaces supported by GDB, and thus free the programmer
  57 from the need to write several versions of the same code, one each for
  58 every UI, to produce output.
  59
  60 <h4 class="subsection">Overview and Terminology</h4>
  61
  62    <p>In general, execution of each GDB command produces some sort
  63 of output, and can even generate an input request.
  64
  65    <p>Output can be generated for the following purposes:
  66
  67      <ul>
  68 <li>to display a <em>result</em> of an operation;
  69
  70      <li>to convey <em>info</em> or produce side-effects of a requested
  71 operation;
  72
  73      <li>to provide a <em>notification</em> of an asynchronous event (including
  74 progress indication of a prolonged asynchronous operation);
  75
  76      <li>to display <em>error messages</em> (including warnings);
  77
  78      <li>to show <em>debug data</em>;
  79
  80      <li>to <em>query</em> or prompt a user for input (a special case).
  81 </ul>
  82
  83 <p>This section mainly concentrates on how to build result output,
  84 although some of it also applies to other kinds of output.
  85
  86    <p>Generation of output that displays the results of an operation
  87 involves one or more of the following:
  88
  89      <ul>
  90 <li>output of the actual data
  91
  92      <li>formatting the output as appropriate for console output, to make it
  93 easily readable by humans
  94
  95      <li>machine oriented formatting-a more terse formatting to allow for easy
  96 parsing by programs which read GDB's output
  97
  98      <li>annotation, whose purpose is to help legacy GUIs to identify interesting
  99 parts in the output
 100 </ul>
 101
 102    <p>The <code>ui_out</code> routines take care of the first three aspects.
 103 Annotations are provided by separate annotation routines.  Note that use
 104 of annotations for an interface between a GUI and GDB is
 105 deprecated.
 106
 107    <p>Output can be in the form of a single item, which we call a <dfn>field</dfn>;
 108 a <dfn>list</dfn> consisting of identical fields; a <dfn>tuple</dfn> consisting of
 109 non-identical fields; or a <dfn>table</dfn>, which is a tuple consisting of a
 110 header and a body.  In a BNF-like form:
 111
 112      <dl>
 113 <dt><code>&lt;table&gt; ==&gt;</code>
 114      <dd><code>&lt;header&gt; &lt;body&gt;</code>
 115 <br><dt><code>&lt;header&gt; ==&gt;</code>
 116      <dd><code>{ &lt;column&gt; }</code>
 117 <br><dt><code>&lt;column&gt; ==&gt;</code>
 118      <dd><code>&lt;width&gt; &lt;alignment&gt; &lt;title&gt;</code>
 119 <br><dt><code>&lt;body&gt; ==&gt;</code>
 120      <dd><code>{&lt;row&gt;}</code>
 121 </dl>
 122
 123 <h4 class="subsection">General Conventions</h4>
 124
 125    <p>Most <code>ui_out</code> routines are of type <code>void</code>, the exceptions are
 126 <code>ui_out_stream_new</code> (which returns a pointer to the newly created
 127 object) and the <code>make_cleanup</code> routines.
 128
 129    <p>The first parameter is always the <code>ui_out</code> vector object, a pointer
 130 to a <code>struct ui_out</code>.
 131
 132    <p>The <var>format</var> parameter is like in <code>printf</code> family of functions.
 133 When it is present, there must also be a variable list of arguments
 134 sufficient used to satisfy the <code>%</code> specifiers in the supplied
 135 format.
 136
 137    <p>When a character string argument is not used in a <code>ui_out</code> function
 138 call, a <code>NULL</code> pointer has to be supplied instead.
 139
 140 <h4 class="subsection">Table, Tuple and List Functions</h4>
 141
 142    <p>This section introduces <code>ui_out</code> routines for building lists,
 143 tuples and tables.  The routines to output the actual data items
 144 (fields) are presented in the next section.
 145
 146    <p>To recap: A <dfn>tuple</dfn> is a sequence of <dfn>fields</dfn>, each field
 147 containing information about an object; a <dfn>list</dfn> is a sequence of
 148 fields where each field describes an identical object.
 149
 150    <p>Use the <dfn>table</dfn> functions when your output consists of a list of
 151 rows (tuples) and the console output should include a heading.  Use this
 152 even when you are listing just one object but you still want the header.
 153
 154    <p>Tables can not be nested.  Tuples and lists can be nested up to a
 155 maximum of five levels.
 156
 157    <p>The overall structure of the table output code is something like this:
 158
 159 <pre class="example">       ui_out_table_begin
 160          ui_out_table_header
 161          ...
 162          ui_out_table_body
 163            ui_out_tuple_begin
 164              ui_out_field_*
 165              ...
 166            ui_out_tuple_end
 167            ...
 168        ui_out_table_end
 169      </pre>
 170
 171    <p>Here is the description of table-, tuple- and list-related <code>ui_out</code>
 172 functions:
 173
 174 <p>
 175 <table width="100%">
 176 <tr>
 177 <td align="left">void <b>ui_out_table_begin</b><i> </i>(<i>struct ui_out *</i><var>uiout</var><i>, int </i><var>nbrofcols</var><i>, int </i><var>nr_rows</var><i>, const char *</i><var>tblid</var><i></i>)<i>
 178      </i></td>
 179 <td align="right">Function</td>
 180 </tr>
 181 </table>
 182 <table width="95%" align="center">
 183 <tr><td>
 184 The function <code>ui_out_table_begin</code> marks the beginning of the output
 185 of a table.  It should always be called before any other <code>ui_out</code>
 186 function for a given table.  <var>nbrofcols</var> is the number of columns in
 187 the table. <var>nr_rows</var> is the number of rows in the table.
 188 <var>tblid</var> is an optional string identifying the table.  The string
 189 pointed to by <var>tblid</var> is copied by the implementation of
 190 <code>ui_out_table_begin</code>, so the application can free the string if it
 191 was <code>malloc</code>ed.
 192
 193      <p>The companion function <code>ui_out_table_end</code>, described below, marks
 194 the end of the table's output.
 195 </td></tr>
 196 </table>
 197
 198 <p>
 199 <table width="100%">
 200 <tr>
 201 <td align="left">void <b>ui_out_table_header</b><i> </i>(<i>struct ui_out *</i><var>uiout</var><i>, int </i><var>width</var><i>, enum ui_align </i><var>alignment</var><i>, const char *</i><var>colhdr</var><i></i>)<i>
 202      </i></td>
 203 <td align="right">Function</td>
 204 </tr>
 205 </table>
 206 <table width="95%" align="center">
 207 <tr><td>
 208 <code>ui_out_table_header</code> provides the header information for a single
 209 table column.  You call this function several times, one each for every
 210 column of the table, after <code>ui_out_table_begin</code>, but before
 211 <code>ui_out_table_body</code>.
 212
 213      <p>The value of <var>width</var> gives the column width in characters.  The
 214 value of <var>alignment</var> is one of <code>left</code>, <code>center</code>, and
 215 <code>right</code>, and it specifies how to align the header: left-justify,
 216 center, or right-justify it.  <var>colhdr</var> points to a string that
 217 specifies the column header; the implementation copies that string, so
 218 column header strings in <code>malloc</code>ed storage can be freed after the
 219 call.
 220 </td></tr>
 221 </table>
 222
 223 <p>
 224 <table width="100%">
 225 <tr>
 226 <td align="left">void <b>ui_out_table_body</b><i> </i>(<i>struct ui_out *</i><var>uiout</var><i></i>)<i>
 227      </i></td>
 228 <td align="right">Function</td>
 229 </tr>
 230 </table>
 231 <table width="95%" align="center">
 232 <tr><td>
 233 This function delimits the table header from the table body.
 234 </td></tr>
 235 </table>
 236
 237 <p>
 238 <table width="100%">
 239 <tr>
 240 <td align="left">void <b>ui_out_table_end</b><i> </i>(<i>struct ui_out *</i><var>uiout</var><i></i>)<i>
 241      </i></td>
 242 <td align="right">Function</td>
 243 </tr>
 244 </table>
 245 <table width="95%" align="center">
 246 <tr><td>
 247 This function signals the end of a table's output.  It should be called
 248 after the table body has been produced by the list and field output
 249 functions.
 250
 251      <p>There should be exactly one call to <code>ui_out_table_end</code> for each
 252 call to <code>ui_out_table_begin</code>, otherwise the <code>ui_out</code> functions
 253 will signal an internal error.
 254 </td></tr>
 255 </table>
 256
 257    <p>The output of the tuples that represent the table rows must follow the
 258 call to <code>ui_out_table_body</code> and precede the call to
 259 <code>ui_out_table_end</code>.  You build a tuple by calling
 260 <code>ui_out_tuple_begin</code> and <code>ui_out_tuple_end</code>, with suitable
 261 calls to functions which actually output fields between them.
 262
 263 <p>
 264 <table width="100%">
 265 <tr>
 266 <td align="left">void <b>ui_out_tuple_begin</b><i> </i>(<i>struct ui_out *</i><var>uiout</var><i>, const char *</i><var>id</var><i></i>)<i>
 267      </i></td>
 268 <td align="right">Function</td>
 269 </tr>
 270 </table>
 271 <table width="95%" align="center">
 272 <tr><td>
 273 This function marks the beginning of a tuple output.  <var>id</var> points
 274 to an optional string that identifies the tuple; it is copied by the
 275 implementation, and so strings in <code>malloc</code>ed storage can be freed
 276 after the call.
 277 </td></tr>
 278 </table>
 279
 280 <p>
 281 <table width="100%">
 282 <tr>
 283 <td align="left">void <b>ui_out_tuple_end</b><i> </i>(<i>struct ui_out *</i><var>uiout</var><i></i>)<i>
 284      </i></td>
 285 <td align="right">Function</td>
 286 </tr>
 287 </table>
 288 <table width="95%" align="center">
 289 <tr><td>
 290 This function signals an end of a tuple output.  There should be exactly
 291 one call to <code>ui_out_tuple_end</code> for each call to
 292 <code>ui_out_tuple_begin</code>, otherwise an internal GDB error will
 293 be signaled.
 294 </td></tr>
 295 </table>
 296
 297 <p>
 298 <table width="100%">
 299 <tr>
 300 <td align="left">struct <b>cleanup</b><i> *make_cleanup_ui_out_tuple_begin_end </i>(<i>struct ui_out *</i><var>uiout</var><i>, const char *</i><var>id</var><i></i>)<i>
 301      </i></td>
 302 <td align="right">Function</td>
 303 </tr>
 304 </table>
 305 <table width="95%" align="center">
 306 <tr><td>
 307 This function first opens the tuple and then establishes a cleanup
 308 (see <a href="Coding.html#Coding">Cleanups</a>) to close the tuple.  It provides a convenient
 309 and correct implementation of the non-portable<a rel="footnote" href="#fn-1"><sup>1</sup></a> code sequence:
 310      <pre class="smallexample">          struct cleanup *old_cleanup;
 311           ui_out_tuple_begin (uiout, "...");
 312           old_cleanup = make_cleanup ((void(*)(void *)) ui_out_tuple_end,
 313                                       uiout);
 314           </pre>
 315      </td></tr>
 316 </table>
 317
 318 <p>
 319 <table width="100%">
 320 <tr>
 321 <td align="left">void <b>ui_out_list_begin</b><i> </i>(<i>struct ui_out *</i><var>uiout</var><i>, const char *</i><var>id</var><i></i>)<i>
 322      </i></td>
 323 <td align="right">Function</td>
 324 </tr>
 325 </table>
 326 <table width="95%" align="center">
 327 <tr><td>
 328 This function marks the beginning of a list output.  <var>id</var> points to
 329 an optional string that identifies the list; it is copied by the
 330 implementation, and so strings in <code>malloc</code>ed storage can be freed
 331 after the call.
 332 </td></tr>
 333 </table>
 334
 335 <p>
 336 <table width="100%">
 337 <tr>
 338 <td align="left">void <b>ui_out_list_end</b><i> </i>(<i>struct ui_out *</i><var>uiout</var><i></i>)<i>
 339      </i></td>
 340 <td align="right">Function</td>
 341 </tr>
 342 </table>
 343 <table width="95%" align="center">
 344 <tr><td>
 345 This function signals an end of a list output.  There should be exactly
 346 one call to <code>ui_out_list_end</code> for each call to
 347 <code>ui_out_list_begin</code>, otherwise an internal GDB error will
 348 be signaled.
 349 </td></tr>
 350 </table>
 351
 352 <p>
 353 <table width="100%">
 354 <tr>
 355 <td align="left">struct <b>cleanup</b><i> *make_cleanup_ui_out_list_begin_end </i>(<i>struct ui_out *</i><var>uiout</var><i>, const char *</i><var>id</var><i></i>)<i>
 356      </i></td>
 357 <td align="right">Function</td>
 358 </tr>
 359 </table>
 360 <table width="95%" align="center">
 361 <tr><td>
 362 Similar to <code>make_cleanup_ui_out_tuple_begin_end</code>, this function
 363 opens a list and then establishes cleanup (see <a href="Coding.html#Coding">Cleanups</a>)
 364 that will close the list.list.
 365 </td></tr>
 366 </table>
 367
 368 <h4 class="subsection">Item Output Functions</h4>
 369
 370    <p>The functions described below produce output for the actual data
 371 items, or fields, which contain information about the object.
 372
 373    <p>Choose the appropriate function accordingly to your particular needs.
 374
 375 <p>
 376 <table width="100%">
 377 <tr>
 378 <td align="left">void <b>ui_out_field_fmt</b><i> </i>(<i>struct ui_out *</i><var>uiout</var><i>, char *</i><var>fldname</var><i>, char *</i><var>format</var><i>, ...</i>)<i>
 379      </i></td>
 380 <td align="right">Function</td>
 381 </tr>
 382 </table>
 383 <table width="95%" align="center">
 384 <tr><td>
 385 This is the most general output function.  It produces the
 386 representation of the data in the variable-length argument list
 387 according to formatting specifications in <var>format</var>, a
 388 <code>printf</code>-like format string.  The optional argument <var>fldname</var>
 389 supplies the name of the field.  The data items themselves are
 390 supplied as additional arguments after <var>format</var>.
 391
 392      <p>This generic function should be used only when it is not possible to
 393 use one of the specialized versions (see below).
 394 </td></tr>
 395 </table>
 396
 397 <p>
 398 <table width="100%">
 399 <tr>
 400 <td align="left">void <b>ui_out_field_int</b><i> </i>(<i>struct ui_out *</i><var>uiout</var><i>, const char *</i><var>fldname</var><i>, int </i><var>value</var><i></i>)<i>
 401      </i></td>
 402 <td align="right">Function</td>
 403 </tr>
 404 </table>
 405 <table width="95%" align="center">
 406 <tr><td>
 407 This function outputs a value of an <code>int</code> variable.  It uses the
 408 <code>"%d"</code> output conversion specification.  <var>fldname</var> specifies
 409 the name of the field.
 410 </td></tr>
 411 </table>
 412
 413 <p>
 414 <table width="100%">
 415 <tr>
 416 <td align="left">void <b>ui_out_field_core_addr</b><i> </i>(<i>struct ui_out *</i><var>uiout</var><i>, const char *</i><var>fldname</var><i>, CORE_ADDR </i><var>address</var><i></i>)<i>
 417      </i></td>
 418 <td align="right">Function</td>
 419 </tr>
 420 </table>
 421 <table width="95%" align="center">
 422 <tr><td>
 423 This function outputs an address.
 424 </td></tr>
 425 </table>
 426
 427 <p>
 428 <table width="100%">
 429 <tr>
 430 <td align="left">void <b>ui_out_field_string</b><i> </i>(<i>struct ui_out *</i><var>uiout</var><i>, const char *</i><var>fldname</var><i>, const char *</i><var>string</var><i></i>)<i>
 431      </i></td>
 432 <td align="right">Function</td>
 433 </tr>
 434 </table>
 435 <table width="95%" align="center">
 436 <tr><td>
 437 This function outputs a string using the <code>"%s"</code> conversion
 438 specification.
 439 </td></tr>
 440 </table>
 441
 442    <p>Sometimes, there's a need to compose your output piece by piece using
 443 functions that operate on a stream, such as <code>value_print</code> or
 444 <code>fprintf_symbol_filtered</code>.  These functions accept an argument of
 445 the type <code>struct ui_file *</code>, a pointer to a <code>ui_file</code> object
 446 used to store the data stream used for the output.  When you use one
 447 of these functions, you need a way to pass their results stored in a
 448 <code>ui_file</code> object to the <code>ui_out</code> functions.  To this end,
 449 you first create a <code>ui_stream</code> object by calling
 450 <code>ui_out_stream_new</code>, pass the <code>stream</code> member of that
 451 <code>ui_stream</code> object to <code>value_print</code> and similar functions,
 452 and finally call <code>ui_out_field_stream</code> to output the field you
 453 constructed.  When the <code>ui_stream</code> object is no longer needed,
 454 you should destroy it and free its memory by calling
 455 <code>ui_out_stream_delete</code>.
 456
 457 <p>
 458 <table width="100%">
 459 <tr>
 460 <td align="left">struct <b>ui_stream</b><i> *ui_out_stream_new </i>(<i>struct ui_out *</i><var>uiout</var><i></i>)<i>
 461      </i></td>
 462 <td align="right">Function</td>
 463 </tr>
 464 </table>
 465 <table width="95%" align="center">
 466 <tr><td>
 467 This function creates a new <code>ui_stream</code> object which uses the
 468 same output methods as the <code>ui_out</code> object whose pointer is
 469 passed in <var>uiout</var>.  It returns a pointer to the newly created
 470 <code>ui_stream</code> object.
 471 </td></tr>
 472 </table>
 473
 474 <p>
 475 <table width="100%">
 476 <tr>
 477 <td align="left">void <b>ui_out_stream_delete</b><i> </i>(<i>struct ui_stream *</i><var>streambuf</var><i></i>)<i>
 478      </i></td>
 479 <td align="right">Function</td>
 480 </tr>
 481 </table>
 482 <table width="95%" align="center">
 483 <tr><td>
 484 This functions destroys a <code>ui_stream</code> object specified by
 485 <var>streambuf</var>.
 486 </td></tr>
 487 </table>
 488
 489 <p>
 490 <table width="100%">
 491 <tr>
 492 <td align="left">void <b>ui_out_field_stream</b><i> </i>(<i>struct ui_out *</i><var>uiout</var><i>, const char *</i><var>fieldname</var><i>, struct ui_stream *</i><var>streambuf</var><i></i>)<i>
 493      </i></td>
 494 <td align="right">Function</td>
 495 </tr>
 496 </table>
 497 <table width="95%" align="center">
 498 <tr><td>
 499 This function consumes all the data accumulated in
 500 <code>streambuf-&gt;stream</code> and outputs it like
 501 <code>ui_out_field_string</code> does.  After a call to
 502 <code>ui_out_field_stream</code>, the accumulated data no longer exists, but
 503 the stream is still valid and may be used for producing more fields.
 504 </td></tr>
 505 </table>
 506
 507    <p><strong>Important:</strong> If there is any chance that your code could bail
 508 out before completing output generation and reaching the point where
 509 <code>ui_out_stream_delete</code> is called, it is necessary to set up a
 510 cleanup, to avoid leaking memory and other resources.  Here's a
 511 skeleton code to do that:
 512
 513 <pre class="smallexample">      struct ui_stream *mybuf = ui_out_stream_new (uiout);
 514       struct cleanup *old = make_cleanup (ui_out_stream_delete, mybuf);
 515       ...
 516       do_cleanups (old);
 517      </pre>
 518
 519    <p>If the function already has the old cleanup chain set (for other kinds
 520 of cleanups), you just have to add your cleanup to it:
 521
 522 <pre class="smallexample">       mybuf = ui_out_stream_new (uiout);
 523        make_cleanup (ui_out_stream_delete, mybuf);
 524      </pre>
 525
 526    <p>Note that with cleanups in place, you should not call
 527 <code>ui_out_stream_delete</code> directly, or you would attempt to free the
 528 same buffer twice.
 529
 530 <h4 class="subsection">Utility Output Functions</h4>
 531
 532 <p>
 533 <table width="100%">
 534 <tr>
 535 <td align="left">void <b>ui_out_field_skip</b><i> </i>(<i>struct ui_out *</i><var>uiout</var><i>, const char *</i><var>fldname</var><i></i>)<i>
 536      </i></td>
 537 <td align="right">Function</td>
 538 </tr>
 539 </table>
 540 <table width="95%" align="center">
 541 <tr><td>
 542 This function skips a field in a table.  Use it if you have to leave
 543 an empty field without disrupting the table alignment.  The argument
 544 <var>fldname</var> specifies a name for the (missing) filed.
 545 </td></tr>
 546 </table>
 547
 548 <p>
 549 <table width="100%">
 550 <tr>
 551 <td align="left">void <b>ui_out_text</b><i> </i>(<i>struct ui_out *</i><var>uiout</var><i>, const char *</i><var>string</var><i></i>)<i>
 552      </i></td>
 553 <td align="right">Function</td>
 554 </tr>
 555 </table>
 556 <table width="95%" align="center">
 557 <tr><td>
 558 This function outputs the text in <var>string</var> in a way that makes it
 559 easy to be read by humans.  For example, the console implementation of
 560 this method filters the text through a built-in pager, to prevent it
 561 from scrolling off the visible portion of the screen.
 562
 563      <p>Use this function for printing relatively long chunks of text around
 564 the actual field data: the text it produces is not aligned according
 565 to the table's format.  Use <code>ui_out_field_string</code> to output a
 566 string field, and use <code>ui_out_message</code>, described below, to
 567 output short messages.
 568 </td></tr>
 569 </table>
 570
 571 <p>
 572 <table width="100%">
 573 <tr>
 574 <td align="left">void <b>ui_out_spaces</b><i> </i>(<i>struct ui_out *</i><var>uiout</var><i>, int </i><var>nspaces</var><i></i>)<i>
 575      </i></td>
 576 <td align="right">Function</td>
 577 </tr>
 578 </table>
 579 <table width="95%" align="center">
 580 <tr><td>
 581 This function outputs <var>nspaces</var> spaces.  It is handy to align the
 582 text produced by <code>ui_out_text</code> with the rest of the table or
 583 list.
 584 </td></tr>
 585 </table>
 586
 587 <p>
 588 <table width="100%">
 589 <tr>
 590 <td align="left">void <b>ui_out_message</b><i> </i>(<i>struct ui_out *</i><var>uiout</var><i>, int </i><var>verbosity</var><i>, const char *</i><var>format</var><i>, ...</i>)<i>
 591      </i></td>
 592 <td align="right">Function</td>
 593 </tr>
 594 </table>
 595 <table width="95%" align="center">
 596 <tr><td>
 597 This function produces a formatted message, provided that the current
 598 verbosity level is at least as large as given by <var>verbosity</var>.  The
 599 current verbosity level is specified by the user with the <code>set
 600 verbositylevel</code> command.<a rel="footnote" href="#fn-2"><sup>2</sup></a>
 601 </td></tr>
 602 </table>
 603
 604 <p>
 605 <table width="100%">
 606 <tr>
 607 <td align="left">void <b>ui_out_wrap_hint</b><i> </i>(<i>struct ui_out *</i><var>uiout</var><i>, char *</i><var>indent</var><i></i>)<i>
 608      </i></td>
 609 <td align="right">Function</td>
 610 </tr>
 611 </table>
 612 <table width="95%" align="center">
 613 <tr><td>
 614 This function gives the console output filter (a paging filter) a hint
 615 of where to break lines which are too long.  Ignored for all other
 616 output consumers.  <var>indent</var>, if non-<code>NULL</code>, is the string to
 617 be printed to indent the wrapped text on the next line; it must remain
 618 accessible until the next call to <code>ui_out_wrap_hint</code>, or until an
 619 explicit newline is produced by one of the other functions.  If
 620 <var>indent</var> is <code>NULL</code>, the wrapped text will not be indented.
 621 </td></tr>
 622 </table>
 623
 624 <p>
 625 <table width="100%">
 626 <tr>
 627 <td align="left">void <b>ui_out_flush</b><i> </i>(<i>struct ui_out *</i><var>uiout</var><i></i>)<i>
 628      </i></td>
 629 <td align="right">Function</td>
 630 </tr>
 631 </table>
 632 <table width="95%" align="center">
 633 <tr><td>
 634 This function flushes whatever output has been accumulated so far, if
 635 the UI buffers output.
 636 </td></tr>
 637 </table>
 638
 639 <h4 class="subsection">Examples of Use of <code>ui_out</code> functions</h4>
 640
 641    <p>This section gives some practical examples of using the <code>ui_out</code>
 642 functions to generalize the old console-oriented code in
 643 GDB.  The examples all come from functions defined on the
 644 <code>breakpoints.c</code> file.
 645
 646    <p>This example, from the <code>breakpoint_1</code> function, shows how to
 647 produce a table.
 648
 649    <p>The original code was:
 650
 651 <pre class="example">      if (!found_a_breakpoint++)
 652         {
 653           annotate_breakpoints_headers ();
 654
 655           annotate_field (0);
 656           printf_filtered ("Num ");
 657           annotate_field (1);
 658           printf_filtered ("Type           ");
 659           annotate_field (2);
 660           printf_filtered ("Disp ");
 661           annotate_field (3);
 662           printf_filtered ("Enb ");
 663           if (addressprint)
 664             {
 665               annotate_field (4);
 666               printf_filtered ("Address    ");
 667             }
 668           annotate_field (5);
 669           printf_filtered ("What\n");
 670
 671           annotate_breakpoints_table ();
 672         }
 673      </pre>
 674
 675    <p>Here's the new version:
 676
 677 <pre class="example">       nr_printable_breakpoints = ...;
 678
 679        if (addressprint)
 680          ui_out_table_begin (ui, 6, nr_printable_breakpoints, "BreakpointTable");
 681        else
 682          ui_out_table_begin (ui, 5, nr_printable_breakpoints, "BreakpointTable");
 683
 684        if (nr_printable_breakpoints &gt; 0)
 685          annotate_breakpoints_headers ();
 686        if (nr_printable_breakpoints &gt; 0)
 687          annotate_field (0);
 688        ui_out_table_header (uiout, 3, ui_left, "number", "Num");                /* 1 */
 689        if (nr_printable_breakpoints &gt; 0)
 690          annotate_field (1);
 691        ui_out_table_header (uiout, 14, ui_left, "type", "Type");                /* 2 */
 692        if (nr_printable_breakpoints &gt; 0)
 693          annotate_field (2);
 694        ui_out_table_header (uiout, 4, ui_left, "disp", "Disp");         /* 3 */
 695        if (nr_printable_breakpoints &gt; 0)
 696          annotate_field (3);
 697        ui_out_table_header (uiout, 3, ui_left, "enabled", "Enb");       /* 4 */
 698        if (addressprint)
 699          {
 700           if (nr_printable_breakpoints &gt; 0)
 701             annotate_field (4);
 702           if (TARGET_ADDR_BIT &lt;= 32)
 703             ui_out_table_header (uiout, 10, ui_left, "addr", "Address");/* 5 */
 704           else
 705             ui_out_table_header (uiout, 18, ui_left, "addr", "Address");/* 5 */
 706          }
 707        if (nr_printable_breakpoints &gt; 0)
 708          annotate_field (5);
 709        ui_out_table_header (uiout, 40, ui_noalign, "what", "What");     /* 6 */
 710        ui_out_table_body (uiout);
 711        if (nr_printable_breakpoints &gt; 0)
 712          annotate_breakpoints_table ();
 713      </pre>
 714
 715    <p>This example, from the <code>print_one_breakpoint</code> function, shows how
 716 to produce the actual data for the table whose structure was defined
 717 in the above example.  The original code was:
 718
 719 <pre class="example">        annotate_record ();
 720         annotate_field (0);
 721         printf_filtered ("%-3d ", b-&gt;number);
 722         annotate_field (1);
 723         if ((int)b-&gt;type &gt; (sizeof(bptypes)/sizeof(bptypes[0]))
 724             || ((int) b-&gt;type != bptypes[(int) b-&gt;type].type))
 725           internal_error ("bptypes table does not describe type #%d.",
 726                           (int)b-&gt;type);
 727         printf_filtered ("%-14s ", bptypes[(int)b-&gt;type].description);
 728         annotate_field (2);
 729         printf_filtered ("%-4s ", bpdisps[(int)b-&gt;disposition]);
 730         annotate_field (3);
 731         printf_filtered ("%-3c ", bpenables[(int)b-&gt;enable]);
 732         ...
 733      </pre>
 734
 735    <p>This is the new version:
 736
 737 <pre class="example">        annotate_record ();
 738         ui_out_tuple_begin (uiout, "bkpt");
 739         annotate_field (0);
 740         ui_out_field_int (uiout, "number", b-&gt;number);
 741         annotate_field (1);
 742         if (((int) b-&gt;type &gt; (sizeof (bptypes) / sizeof (bptypes[0])))
 743             || ((int) b-&gt;type != bptypes[(int) b-&gt;type].type))
 744           internal_error ("bptypes table does not describe type #%d.",
 745                           (int) b-&gt;type);
 746         ui_out_field_string (uiout, "type", bptypes[(int)b-&gt;type].description);
 747         annotate_field (2);
 748         ui_out_field_string (uiout, "disp", bpdisps[(int)b-&gt;disposition]);
 749         annotate_field (3);
 750         ui_out_field_fmt (uiout, "enabled", "%c", bpenables[(int)b-&gt;enable]);
 751         ...
 752      </pre>
 753
 754    <p>This example, also from <code>print_one_breakpoint</code>, shows how to
 755 produce a complicated output field using the <code>print_expression</code>
 756 functions which requires a stream to be passed.  It also shows how to
 757 automate stream destruction with cleanups.  The original code was:
 758
 759 <pre class="example">         annotate_field (5);
 760          print_expression (b-&gt;exp, gdb_stdout);
 761      </pre>
 762
 763    <p>The new version is:
 764
 765 <pre class="example">       struct ui_stream *stb = ui_out_stream_new (uiout);
 766        struct cleanup *old_chain = make_cleanup_ui_out_stream_delete (stb);
 767        ...
 768        annotate_field (5);
 769        print_expression (b-&gt;exp, stb-&gt;stream);
 770        ui_out_field_stream (uiout, "what", local_stream);
 771      </pre>
 772
 773    <p>This example, also from <code>print_one_breakpoint</code>, shows how to use
 774 <code>ui_out_text</code> and <code>ui_out_field_string</code>.  The original code
 775 was:
 776
 777 <pre class="example">       annotate_field (5);
 778        if (b-&gt;dll_pathname == NULL)
 779          printf_filtered ("&lt;any library&gt; ");
 780        else
 781          printf_filtered ("library \"%s\" ", b-&gt;dll_pathname);
 782      </pre>
 783
 784    <p>It became:
 785
 786 <pre class="example">       annotate_field (5);
 787        if (b-&gt;dll_pathname == NULL)
 788          {
 789            ui_out_field_string (uiout, "what", "&lt;any library&gt;");
 790            ui_out_spaces (uiout, 1);
 791          }
 792        else
 793          {
 794            ui_out_text (uiout, "library \"");
 795            ui_out_field_string (uiout, "what", b-&gt;dll_pathname);
 796            ui_out_text (uiout, "\" ");
 797          }
 798      </pre>
 799
 800    <p>The following example from <code>print_one_breakpoint</code> shows how to
 801 use <code>ui_out_field_int</code> and <code>ui_out_spaces</code>.  The original
 802 code was:
 803
 804 <pre class="example">       annotate_field (5);
 805        if (b-&gt;forked_inferior_pid != 0)
 806          printf_filtered ("process %d ", b-&gt;forked_inferior_pid);
 807      </pre>
 808
 809    <p>It became:
 810
 811 <pre class="example">       annotate_field (5);
 812        if (b-&gt;forked_inferior_pid != 0)
 813          {
 814            ui_out_text (uiout, "process ");
 815            ui_out_field_int (uiout, "what", b-&gt;forked_inferior_pid);
 816            ui_out_spaces (uiout, 1);
 817          }
 818      </pre>
 819
 820    <p>Here's an example of using <code>ui_out_field_string</code>.  The original
 821 code was:
 822
 823 <pre class="example">       annotate_field (5);
 824        if (b-&gt;exec_pathname != NULL)
 825          printf_filtered ("program \"%s\" ", b-&gt;exec_pathname);
 826      </pre>
 827
 828    <p>It became:
 829
 830 <pre class="example">       annotate_field (5);
 831        if (b-&gt;exec_pathname != NULL)
 832          {
 833            ui_out_text (uiout, "program \"");
 834            ui_out_field_string (uiout, "what", b-&gt;exec_pathname);
 835            ui_out_text (uiout, "\" ");
 836          }
 837      </pre>
 838
 839    <p>Finally, here's an example of printing an address.  The original code:
 840
 841 <pre class="example">       annotate_field (4);
 842        printf_filtered ("%s ",
 843              local_hex_string_custom ((unsigned long) b-&gt;address, "08l"));
 844      </pre>
 845
 846    <p>It became:
 847
 848 <pre class="example">       annotate_field (4);
 849        ui_out_field_core_addr (uiout, "Address", b-&gt;address);
 850      </pre>
 851
 852 <h3 class="section">Console Printing</h3>
 853
 854 <h3 class="section">TUI</h3>
 855
 856    <div class="footnote">
 857 <hr>
 858 <h4>Footnotes</h4>
 859 <ol type="1">
 860 <li><a name="fn-1"></a>
 861 <p>The function
 862 cast is not portable ISO-C.</p>
 863
 864    <li><a name="fn-2"></a>
 865 <p>As of this writing (April 2001),
 866 setting verbosity level is not yet implemented, and is always returned
 867 as zero.  So calling <code>ui_out_message</code> with a <var>verbosity</var>
 868 argument more than zero will cause the message to never be printed.</p>
 869
 870    </ol><hr></div>
 871
 872    </body></html>
 873