gdb/valprint.h

   1 /* Declarations for value printing routines for GDB, the GNU debugger.
   2
   3    Copyright (C) 1986-2024 Free Software Foundation, Inc.
   4
   5    This file is part of GDB.
   6
   7    This program is free software; you can redistribute it and/or modify
   8    it under the terms of the GNU General Public License as published by
   9    the Free Software Foundation; either version 3 of the License, or
  10    (at your option) any later version.
  11
  12    This program is distributed in the hope that it will be useful,
  13    but WITHOUT ANY WARRANTY; without even the implied warranty of
  14    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  15    GNU General Public License for more details.
  16
  17    You should have received a copy of the GNU General Public License
  18    along with this program.  If not, see <http://www.gnu.org/licenses/>.  */
  19
  20 #ifndef VALPRINT_H
  21 #define VALPRINT_H
  22
  23 #include "cli/cli-option.h"
  24
  25 /* Possibilities for prettyformat parameters to routines which print
  26    things.  */
  27
  28 enum val_prettyformat
  29   {
  30     Val_no_prettyformat = 0,
  31     Val_prettyformat,
  32     /* * Use the default setting which the user has specified.  */
  33     Val_prettyformat_default
  34   };
  35
  36 /* This is used to pass formatting options to various value-printing
  37    functions.  */
  38 struct value_print_options
  39 {
  40   /* Pretty-formatting control.  */
  41   enum val_prettyformat prettyformat;
  42
  43   /* Controls pretty formatting of arrays.  */
  44   bool prettyformat_arrays;
  45
  46   /* Controls pretty formatting of structures.  */
  47   bool prettyformat_structs;
  48
  49   /* Controls printing of virtual tables.  */
  50   bool vtblprint;
  51
  52   /* Controls printing of nested unions.  */
  53   bool unionprint;
  54
  55   /* Controls printing of addresses.  */
  56   bool addressprint;
  57
  58   /* Controls printing of nibbles.  */
  59   bool nibblesprint;
  60
  61   /* Controls looking up an object's derived type using what we find
  62      in its vtables.  */
  63   bool objectprint;
  64
  65   /* Maximum number of elements to print for vector contents, or UINT_MAX
  66      for no limit.  Note that "set print elements 0" stores UINT_MAX in
  67      print_max, which displays in a show command as "unlimited".  */
  68   unsigned int print_max;
  69
  70   /* Maximum number of string chars to print for a string pointer value,
  71      zero if to follow the value of print_max, or UINT_MAX for no limit.  */
  72   unsigned int print_max_chars;
  73
  74   /* Print repeat counts if there are more than this many repetitions
  75      of an element in an array.  */
  76   unsigned int repeat_count_threshold;
  77
  78   /* The global output format letter.  */
  79   int output_format;
  80
  81   /* The current format letter.  This is set locally for a given call,
  82      e.g. when the user passes a format to "print".  */
  83   int format;
  84
  85   /* Print memory tag violations for pointers.  */
  86   bool memory_tag_violations;
  87
  88   /* Stop printing at null character?  */
  89   bool stop_print_at_null;
  90
  91   /* True if we should print the index of each element when printing
  92      an array.  */
  93   bool print_array_indexes;
  94
  95   /* If true, then dereference references, otherwise just print
  96      them like pointers.  */
  97   bool deref_ref;
  98
  99   /* If true, print static fields.  */
 100   bool static_field_print;
 101
 102   /* If true, print static fields for Pascal.  FIXME: C++ has a
 103      flag, why not share with Pascal too?  */
 104   bool pascal_static_field_print;
 105
 106   /* If true, don't do Python pretty-printing.  */
 107   bool raw;
 108
 109   /* If true, print the value in "summary" form.
 110      If raw and summary are both true, don't print non-scalar values
 111      ("..." is printed instead).  */
 112   bool summary;
 113
 114   /* If true, when printing a pointer, print the symbol to which it
 115      points, if any.  */
 116   bool symbol_print;
 117
 118   /* Maximum print depth when printing nested aggregates.  */
 119   int max_depth;
 120 };
 121
 122 /* The value to use for `print_max_chars' to follow `print_max'.  */
 123 #define PRINT_MAX_CHARS_ELEMENTS 0
 124
 125 /* The value to use for `print_max_chars' for no limit.  */
 126 #define PRINT_MAX_CHARS_UNLIMITED UINT_MAX
 127
 128 /* Return the character count limit for printing strings.  */
 129
 130 static inline unsigned int
 131 get_print_max_chars (const struct value_print_options *options)
 132 {
 133   return (options->print_max_chars != PRINT_MAX_CHARS_ELEMENTS
 134           ? options->print_max_chars : options->print_max);
 135 }
 136
 137 /* Create an option_def_group for the value_print options, with OPTS
 138    as context.  */
 139 extern gdb::option::option_def_group make_value_print_options_def_group
 140   (value_print_options *opts);
 141
 142 /* The global print options set by the user.  In general this should
 143    not be directly accessed, except by set/show commands.  Ordinary
 144    code should call get_user_print_options instead.  */
 145 extern struct value_print_options user_print_options;
 146
 147 /* Initialize *OPTS to be a copy of the user print options.  */
 148 extern void get_user_print_options (struct value_print_options *opts);
 149
 150 /* Initialize *OPTS to be a copy of the user print options, but with
 151    pretty-formatting disabled.  */
 152 extern void get_no_prettyformat_print_options (struct value_print_options *);
 153
 154 /* Initialize *OPTS to be a copy of the user print options, but using
 155    FORMAT as the formatting option.  */
 156 extern void get_formatted_print_options (struct value_print_options *opts,
 157                                          char format);
 158
 159 extern void maybe_print_array_index (struct type *index_type, LONGEST index,
 160                                      struct ui_file *stream,
 161                                      const struct value_print_options *);
 162
 163
 164 /* Print elements of an array.  */
 165
 166 extern void value_print_array_elements (struct value *, struct ui_file *, int,
 167                                         const struct value_print_options *,
 168                                         unsigned int);
 169
 170 /* Print a scalar according to OPTIONS and SIZE on STREAM.  Format 'i'
 171    is not supported at this level.
 172
 173    This is how the elements of an array or structure are printed
 174    with a format.  */
 175
 176 extern void value_print_scalar_formatted
 177   (struct value *val, const struct value_print_options *options,
 178    int size, struct ui_file *stream);
 179
 180 extern void print_binary_chars (struct ui_file *, const gdb_byte *,
 181                                 unsigned int, enum bfd_endian, bool,
 182                                 const struct value_print_options *options);
 183
 184 extern void print_octal_chars (struct ui_file *, const gdb_byte *,
 185                                unsigned int, enum bfd_endian);
 186
 187 extern void print_decimal_chars (struct ui_file *, const gdb_byte *,
 188                                  unsigned int, bool, enum bfd_endian);
 189
 190 extern void print_hex_chars (struct ui_file *, const gdb_byte *,
 191                              unsigned int, enum bfd_endian, bool);
 192
 193 extern void print_function_pointer_address (const struct value_print_options *options,
 194                                             struct gdbarch *gdbarch,
 195                                             CORE_ADDR address,
 196                                             struct ui_file *stream);
 197
 198 /* Helper function to check the validity of some bits of a value.
 199
 200    If TYPE represents some aggregate type (e.g., a structure), return 1.
 201
 202    Otherwise, any of the bytes starting at OFFSET and extending for
 203    TYPE->length () bytes are invalid, print a message to STREAM and
 204    return 0.  The checking is done using FUNCS.
 205
 206    Otherwise, return 1.  */
 207
 208 extern int valprint_check_validity (struct ui_file *stream, struct type *type,
 209                                     LONGEST embedded_offset,
 210                                     const struct value *val);
 211
 212 extern void val_print_optimized_out (const struct value *val,
 213                                      struct ui_file *stream);
 214
 215 /* Prints "<not saved>" to STREAM.  */
 216 extern void val_print_not_saved (struct ui_file *stream);
 217
 218 extern void val_print_unavailable (struct ui_file *stream);
 219
 220 extern void val_print_invalid_address (struct ui_file *stream);
 221
 222 /* An instance of this is passed to generic_val_print and describes
 223    some language-specific ways to print things.  */
 224
 225 struct generic_val_print_decorations
 226 {
 227   /* Printing complex numbers: what to print before, between the
 228      elements, and after.  */
 229
 230   const char *complex_prefix;
 231   const char *complex_infix;
 232   const char *complex_suffix;
 233
 234   /* Boolean true and false.  */
 235
 236   const char *true_name;
 237   const char *false_name;
 238
 239   /* What to print when we see TYPE_CODE_VOID.  */
 240
 241   const char *void_name;
 242
 243   /* Array start and end strings.  */
 244   const char *array_start;
 245   const char *array_end;
 246 };
 247
 248
 249 /* Print a value in a generic way.  VAL is the value, STREAM is where
 250    to print it, RECURSE is the recursion depth, OPTIONS describe how
 251    the printing should be done, and D is the language-specific
 252    decorations object.  Note that structs and unions cannot be printed
 253    by this function.  */
 254
 255 extern void generic_value_print (struct value *val, struct ui_file *stream,
 256                                  int recurse,
 257                                  const struct value_print_options *options,
 258                                  const struct generic_val_print_decorations *d);
 259
 260 extern void generic_emit_char (int c, struct type *type, struct ui_file *stream,
 261                                int quoter, const char *encoding);
 262
 263 extern void generic_printstr (struct ui_file *stream, struct type *type,
 264                               const gdb_byte *string, unsigned int length,
 265                               const char *encoding, int force_ellipses,
 266                               int quote_char, int c_style_terminator,
 267                               const struct value_print_options *options);
 268
 269 /* Run the "output" command.  ARGS and FROM_TTY are the usual
 270    arguments passed to all command implementations, except ARGS is
 271    const.  */
 272
 273 extern void output_command (const char *args, int from_tty);
 274
 275 extern int val_print_scalar_type_p (struct type *type);
 276
 277 struct format_data
 278   {
 279     int count;
 280     char format;
 281     char size;
 282     bool print_tags;
 283
 284     /* True if the value should be printed raw -- that is, bypassing
 285        python-based formatters.  */
 286     unsigned char raw;
 287   };
 288
 289 extern void print_command_parse_format (const char **expp, const char *cmdname,
 290                                         value_print_options *opts);
 291
 292 /* Print VAL to console according to OPTS, including recording it to
 293    the history.  */
 294 extern void print_value (value *val, const value_print_options &opts);
 295
 296 /* Completer for the "print", "call", and "compile print"
 297    commands.  */
 298 extern void print_command_completer (struct cmd_list_element *ignore,
 299                                      completion_tracker &tracker,
 300                                      const char *text, const char *word);
 301
 302 /* Given an address ADDR return all the elements needed to print the
 303    address in a symbolic form.  NAME can be mangled or not depending
 304    on DO_DEMANGLE (and also on the asm_demangle global variable,
 305    manipulated via ''set print asm-demangle'').  When
 306    PREFER_SYM_OVER_MINSYM is true, names (and offsets) from minimal
 307    symbols won't be used except in instances where no symbol was
 308    found; otherwise, a minsym might be used in some instances (mostly
 309    involving function with non-contiguous address ranges).  Return
 310    0 in case of success, when all the info in the OUT parameters is
 311    valid.  Return 1 otherwise.  */
 312
 313 extern int build_address_symbolic (struct gdbarch *,
 314                                    CORE_ADDR addr,
 315                                    bool do_demangle,
 316                                    bool prefer_sym_over_minsym,
 317                                    std::string *name,
 318                                    int *offset,
 319                                    std::string *filename,
 320                                    int *line,
 321                                    int *unmapped);
 322
 323 /* Check to see if RECURSE is greater than or equal to the allowed
 324    printing max-depth (see 'set print max-depth').  If it is then print an
 325    ellipsis expression to STREAM and return true, otherwise return false.
 326    LANGUAGE determines what type of ellipsis expression is printed.  */
 327
 328 extern bool val_print_check_max_depth (struct ui_file *stream, int recurse,
 329                                        const struct value_print_options *opts,
 330                                        const struct language_defn *language);
 331
 332 /* Like common_val_print, but call value_check_printable first.  */
 333
 334 extern void common_val_print_checked
 335   (struct value *val,
 336    struct ui_file *stream, int recurse,
 337    const struct value_print_options *options,
 338    const struct language_defn *language);
 339
 340 #endif