gdbint.texinfo

这个是LINUX下的GDB调度工具的源码

@cindex item output functions
@cindex field output functions
@cindex data output
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.

@deftypefun void ui_out_field_fmt (struct ui_out *@var{uiout}, char *@var{fldname}, char *@var{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 @var{format}, a
@code{printf}-like format string.  The optional argument @var{fldname}
supplies the name of the field.  The data items themselves are
supplied as additional arguments after @var{format}.

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

@deftypefun void ui_out_field_int (struct ui_out *@var{uiout}, const char *@var{fldname}, int @var{value})
This function outputs a value of an @code{int} variable.  It uses the
@code{"%d"} output conversion specification.  @var{fldname} specifies
the name of the field.
@end deftypefun

@deftypefun void ui_out_field_fmt_int (struct ui_out *@var{uiout}, int @var{width}, enum ui_align @var{alignment}, const char *@var{fldname}, int @var{value})
This function outputs a value of an @code{int} variable.  It differs from
@code{ui_out_field_int} in that the caller specifies the desired @var{width} and @var{alignment} of the output.
@var{fldname} specifies
the name of the field.
@end deftypefun

@deftypefun void ui_out_field_core_addr (struct ui_out *@var{uiout}, const char *@var{fldname}, CORE_ADDR @var{address})
This function outputs an address.
@end deftypefun

@deftypefun void ui_out_field_string (struct ui_out *@var{uiout}, const char *@var{fldname}, const char *@var{string})
This function outputs a string using the @code{"%s"} conversion
specification.
@end deftypefun

Sometimes, there's a need to compose your output piece by piece using
functions that operate on a stream, such as @code{value_print} or
@code{fprintf_symbol_filtered}.  These functions accept an argument of
the type @code{struct ui_file *}, a pointer to a @code{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
@code{ui_file} object to the @code{ui_out} functions.  To this end,
you first create a @code{ui_stream} object by calling
@code{ui_out_stream_new}, pass the @code{stream} member of that
@code{ui_stream} object to @code{value_print} and similar functions,
and finally call @code{ui_out_field_stream} to output the field you
constructed.  When the @code{ui_stream} object is no longer needed,
you should destroy it and free its memory by calling
@code{ui_out_stream_delete}.

@deftypefun struct ui_stream *ui_out_stream_new (struct ui_out *@var{uiout})
This function creates a new @code{ui_stream} object which uses the
same output methods as the @code{ui_out} object whose pointer is
passed in @var{uiout}.  It returns a pointer to the newly created
@code{ui_stream} object.
@end deftypefun

@deftypefun void ui_out_stream_delete (struct ui_stream *@var{streambuf})
This functions destroys a @code{ui_stream} object specified by
@var{streambuf}.
@end deftypefun

@deftypefun void ui_out_field_stream (struct ui_out *@var{uiout}, const char *@var{fieldname}, struct ui_stream *@var{streambuf})
This function consumes all the data accumulated in
@code{streambuf->stream} and outputs it like
@code{ui_out_field_string} does.  After a call to
@code{ui_out_field_stream}, the accumulated data no longer exists, but
the stream is still valid and may be used for producing more fields.
@end deftypefun

@strong{Important:} 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} 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:

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

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

@smallexample
  mybuf = ui_out_stream_new (uiout);
  make_cleanup (ui_out_stream_delete, mybuf);
@end smallexample

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

@subsection Utility Output Functions

@deftypefun void ui_out_field_skip (struct ui_out *@var{uiout}, const char *@var{fldname})
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} specifies a name for the (missing) filed.
@end deftypefun

@deftypefun void ui_out_text (struct ui_out *@var{uiout}, const char *@var{string})
This function outputs the text in @var{string} 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.

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} to output a
string field, and use @code{ui_out_message}, described below, to
output short messages.
@end deftypefun

@deftypefun void ui_out_spaces (struct ui_out *@var{uiout}, int @var{nspaces})
This function outputs @var{nspaces} spaces.  It is handy to align the
text produced by @code{ui_out_text} with the rest of the table or
list.
@end deftypefun

@deftypefun void ui_out_message (struct ui_out *@var{uiout}, int @var{verbosity}, const char *@var{format}, ...)
This function produces a formatted message, provided that the current
verbosity level is at least as large as given by @var{verbosity}.  The
current verbosity level is specified by the user with the @samp{set
verbositylevel} command.@footnote{As of this writing (April 2001),
setting verbosity level is not yet implemented, and is always returned
as zero.  So calling @code{ui_out_message} with a @var{verbosity}
argument more than zero will cause the message to never be printed.}
@end deftypefun

@deftypefun void ui_out_wrap_hint (struct ui_out *@var{uiout}, char *@var{indent})
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}, if non-@code{NULL}, 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}, or until an
explicit newline is produced by one of the other functions.  If
@var{indent} is @code{NULL}, the wrapped text will not be indented.
@end deftypefun

@deftypefun void ui_out_flush (struct ui_out *@var{uiout})
This function flushes whatever output has been accumulated so far, if
the UI buffers output.
@end deftypefun


@subsection Examples of Use of @code{ui_out} functions

@cindex using @code{ui_out} functions
@cindex @code{ui_out} functions, usage examples
This section gives some practical examples of using the @code{ui_out}
functions to generalize the old console-oriented code in
@value{GDBN}.  The examples all come from functions defined on the
@file{breakpoints.c} file.

This example, from the @code{breakpoint_1} function, shows how to
produce a table.

The original code was:

@smallexample
 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 ();
   @}
@end smallexample

Here's the new version:

@smallexample
  nr_printable_breakpoints = @dots{};

  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 > 0)
    annotate_breakpoints_headers ();
  if (nr_printable_breakpoints > 0)
    annotate_field (0);
  ui_out_table_header (uiout, 3, ui_left, "number", "Num");		/* 1 */
  if (nr_printable_breakpoints > 0)
    annotate_field (1);
  ui_out_table_header (uiout, 14, ui_left, "type", "Type");		/* 2 */
  if (nr_printable_breakpoints > 0)
    annotate_field (2);
  ui_out_table_header (uiout, 4, ui_left, "disp", "Disp");		/* 3 */
  if (nr_printable_breakpoints > 0)
    annotate_field (3);
  ui_out_table_header (uiout, 3, ui_left, "enabled", "Enb");	/* 4 */
  if (addressprint)
    @{
     if (nr_printable_breakpoints > 0)
       annotate_field (4);
     if (TARGET_ADDR_BIT <= 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 > 0)
    annotate_field (5);
  ui_out_table_header (uiout, 40, ui_noalign, "what", "What");	/* 6 */
  ui_out_table_body (uiout);
  if (nr_printable_breakpoints > 0)
    annotate_breakpoints_table ();
@end smallexample

This example, from the @code{print_one_breakpoint} function, shows how
to produce the actual data for the table whose structure was defined
in the above example.  The original code was:

@smallexample
   annotate_record ();
   annotate_field (0);
   printf_filtered ("%-3d ", b->number);
   annotate_field (1);
   if ((int)b->type > (sizeof(bptypes)/sizeof(bptypes[0]))
       || ((int) b->type != bptypes[(int) b->type].type))
     internal_error ("bptypes table does not describe type #%d.",
                     (int)b->type);
   printf_filtered ("%-14s ", bptypes[(int)b->type].description);
   annotate_field (2);
   printf_filtered ("%-4s ", bpdisps[(int)b->disposition]);
   annotate_field (3);
   printf_filtered ("%-3c ", bpenables[(int)b->enable]);
   @dots{}
@end smallexample

This is the new version:

@smallexample
   annotate_record ();
   ui_out_tuple_begin (uiout, "bkpt");
   annotate_field (0);
   ui_out_field_int (uiout, "number", b->number);
   annotate_field (1);
   if (((int) b->type > (sizeof (bptypes) / sizeof (bptypes[0])))
       || ((int) b->type != bptypes[(int) b->type].type))
     internal_error ("bptypes table does not describe type #%d.",
                     (int) b->type);
   ui_out_field_string (uiout, "type", bptypes[(int)b->type].description);
   annotate_field (2);
   ui_out_field_string (uiout, "disp", bpdisps[(int)b->disposition]);
   annotate_field (3);
   ui_out_field_fmt (uiout, "enabled", "%c", bpenables[(int)b->enable]);
   @dots{}
@end smallexample

This example, also from @code{print_one_breakpoint}, shows how to
produce a complicated output field using the @code{print_expression}
functions which requires a stream to be passed.  It also shows how to
automate stream destruction with cleanups.  The original code was:

@smallexample
    annotate_field (5);
    print_expression (b->exp, gdb_stdout);
@end smallexample

The new version is:

@smallexample
  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->exp, stb->stream);
  ui_out_field_stream (uiout, "what", local_stream);
@end smallexample

This example, also from @code{print_one_breakpoint}, shows how to use
@code{ui_out_text} and @code{ui_out_field_string}.  The original code
was:

@smallexample
  annotate_field (5);
  if (b->dll_pathname == NULL)
    printf_filtered ("<any library> ");
  else
    printf_filtered ("library \"%s\" ", b->dll_pathname);
@end smallexample

It became:

@smallexample
  annotate_field (5);
  if (b->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->dll_pathname);
      ui_out_text (uiout, "\" ");
    @}
@end smallexample

The following example from @code{print_one_breakpoint} shows how to
use @code{ui_out_field_int} and @code{ui_out_spaces}.  The original
code was:

@smallexample
  annotate_field (5);
  if (b->forked_inferior_pid != 0)
    printf_filtered ("process %d ", b->forked_inferior_pid);
@end smallexample