gdb/utils.h

   1 /* I/O, string, cleanup, and other random utilities for GDB.
   2    Copyright (C) 1986-2025 Free Software Foundation, Inc.
   3
   4    This file is part of GDB.
   5
   6    This program is free software; you can redistribute it and/or modify
   7    it under the terms of the GNU General Public License as published by
   8    the Free Software Foundation; either version 3 of the License, or
   9    (at your option) any later version.
  10
  11    This program is distributed in the hope that it will be useful,
  12    but WITHOUT ANY WARRANTY; without even the implied warranty of
  13    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  14    GNU General Public License for more details.
  15
  16    You should have received a copy of the GNU General Public License
  17    along with this program.  If not, see <http://www.gnu.org/licenses/>.  */
  18
  19 #ifndef GDB_UTILS_H
  20 #define GDB_UTILS_H
  21
  22 #include <chrono>
  23
  24 struct completion_match_for_lcd;
  25 class compiled_regex;
  26
  27 /* String utilities.  */
  28
  29 extern bool sevenbit_strings;
  30
  31 /* Modes of operation for strncmp_iw_with_mode.  */
  32
  33 enum class strncmp_iw_mode
  34 {
  35 /* Do a strcmp() type operation on STRING1 and STRING2, ignoring any
  36    differences in whitespace.  Returns 0 if they match, non-zero if
  37    they don't (slightly different than strcmp()'s range of return
  38    values).  */
  39   NORMAL,
  40
  41   /* Like NORMAL, but also apply the strcmp_iw hack.  I.e.,
  42      string1=="FOO(PARAMS)" matches string2=="FOO".  */
  43   MATCH_PARAMS,
  44 };
  45
  46 /* Helper for strcmp_iw and strncmp_iw.  Exported so that languages
  47    can implement both NORMAL and MATCH_PARAMS variants in a single
  48    function and defer part of the work to strncmp_iw_with_mode.
  49
  50    LANGUAGE is used to implement some context-sensitive
  51    language-specific comparisons.  For example, for C++,
  52    "string1=operator()" should not match "string2=operator" even in
  53    MATCH_PARAMS mode.
  54
  55    MATCH_FOR_LCD is passed down so that the function can mark parts of
  56    the symbol name as ignored for completion matching purposes (e.g.,
  57    to handle abi tags).  If IGNORE_TEMPLATE_PARAMS is true, all template
  58    parameter lists will be ignored when language is C++.  */
  59
  60 extern int strncmp_iw_with_mode
  61   (const char *string1, const char *string2, size_t string2_len,
  62    strncmp_iw_mode mode, enum language language,
  63    completion_match_for_lcd *match_for_lcd = NULL,
  64    bool ignore_template_params = false);
  65
  66 /* Do a strncmp() type operation on STRING1 and STRING2, ignoring any
  67    differences in whitespace.  STRING2_LEN is STRING2's length.
  68    Returns 0 if STRING1 matches STRING2_LEN characters of STRING2,
  69    non-zero otherwise (slightly different than strncmp()'s range of
  70    return values).  Note: passes language_minimal to
  71    strncmp_iw_with_mode, and should therefore be avoided if a more
  72    suitable language is available.  */
  73 extern int strncmp_iw (const char *string1, const char *string2,
  74                        size_t string2_len);
  75
  76 /* Do a strcmp() type operation on STRING1 and STRING2, ignoring any
  77    differences in whitespace.  Returns 0 if they match, non-zero if
  78    they don't (slightly different than strcmp()'s range of return
  79    values).
  80
  81    As an extra hack, string1=="FOO(ARGS)" matches string2=="FOO".
  82    This "feature" is useful when searching for matching C++ function
  83    names (such as if the user types 'break FOO', where FOO is a
  84    mangled C++ function).
  85
  86    Note: passes language_minimal to strncmp_iw_with_mode, and should
  87    therefore be avoided if a more suitable language is available.  */
  88 extern int strcmp_iw (const char *string1, const char *string2);
  89
  90 extern int strcmp_iw_ordered (const char *, const char *);
  91
  92 /* Reset the prompt_for_continue clock.  */
  93 void reset_prompt_for_continue_wait_time (void);
  94 /* Return the time spent in prompt_for_continue.  */
  95 std::chrono::steady_clock::duration get_prompt_for_continue_wait_time ();
  96 \f
  97 /* Parsing utilities.  */
  98
  99 extern int parse_pid_to_attach (const char *args);
 100
 101 extern int parse_escape (struct gdbarch *, const char **);
 102
 103 \f
 104 /* Cleanup utilities.  */
 105
 106 extern void init_page_info (void);
 107
 108 /* Temporarily set BATCH_FLAG and the associated unlimited terminal size.
 109    Restore when destroyed.  */
 110
 111 struct set_batch_flag_and_restore_page_info
 112 {
 113 public:
 114
 115   set_batch_flag_and_restore_page_info ();
 116   ~set_batch_flag_and_restore_page_info ();
 117
 118   DISABLE_COPY_AND_ASSIGN (set_batch_flag_and_restore_page_info);
 119
 120 private:
 121
 122   /* Note that this doesn't use scoped_restore, because it's important
 123      to control the ordering of operations in the destruction, and it
 124      was simpler to avoid introducing a new ad hoc class.  */
 125   unsigned m_save_lines_per_page;
 126   unsigned m_save_chars_per_line;
 127   int m_save_batch_flag;
 128 };
 129
 130 \f
 131 /* Path utilities.  */
 132
 133 extern int gdb_filename_fnmatch (const char *pattern, const char *string,
 134                                  int flags);
 135
 136 std::string gdb_ldirname (const char *filename);
 137
 138 extern int count_path_elements (const char *path);
 139
 140 extern const char *strip_leading_path_elements (const char *path, int n);
 141 \f
 142 /* GDB output, ui_file utilities.  */
 143
 144 struct ui_file;
 145
 146 extern int query (const char *, ...) ATTRIBUTE_PRINTF (1, 2);
 147 extern int nquery (const char *, ...) ATTRIBUTE_PRINTF (1, 2);
 148 extern int yquery (const char *, ...) ATTRIBUTE_PRINTF (1, 2);
 149
 150 extern void begin_line (void);
 151
 152 extern void wrap_here (int);
 153
 154 extern void reinitialize_more_filter (void);
 155
 156 /* Return the number of characters in a line.  */
 157
 158 extern int get_chars_per_line ();
 159
 160 extern bool pagination_enabled;
 161
 162 /* A flag indicating whether to timestamp debugging messages.  */
 163 extern bool debug_timestamp;
 164
 165 extern struct ui_file **current_ui_gdb_stdout_ptr (void);
 166 extern struct ui_file **current_ui_gdb_stdin_ptr (void);
 167 extern struct ui_file **current_ui_gdb_stderr_ptr (void);
 168 extern struct ui_file **current_ui_gdb_stdlog_ptr (void);
 169
 170 /* Flush STREAM.  */
 171 extern void gdb_flush (struct ui_file *stream);
 172
 173 /* The current top level's ui_file streams.  */
 174
 175 /* Normal results */
 176 #define gdb_stdout (*current_ui_gdb_stdout_ptr ())
 177 /* Input stream */
 178 #define gdb_stdin (*current_ui_gdb_stdin_ptr ())
 179 /* Serious error notifications.  This bypasses the pager, if one is in
 180    use.  */
 181 #define gdb_stderr (*current_ui_gdb_stderr_ptr ())
 182 /* Log/debug/trace messages that bypasses the pager, if one is in
 183    use.  */
 184 #define gdb_stdlog (*current_ui_gdb_stdlog_ptr ())
 185
 186 /* Truly global ui_file streams.  These are all defined in main.c.  */
 187
 188 /* Target output that should bypass the pager, if one is in use.  */
 189 extern struct ui_file *gdb_stdtarg;
 190 extern struct ui_file *gdb_stdtargin;
 191
 192 /* Set the screen dimensions to WIDTH and HEIGHT.  */
 193
 194 extern void set_screen_width_and_height (int width, int height);
 195
 196 /* Generic stdio-like operations.  */
 197
 198 extern void gdb_puts (const char *, struct ui_file *);
 199
 200 extern void gdb_puts (const std::string &s, ui_file *stream);
 201
 202 extern void gdb_putc (int c, struct ui_file *);
 203
 204 extern void gdb_putc (int c);
 205
 206 extern void gdb_puts (const char *);
 207
 208 extern void puts_tabular (char *string, int width, int right);
 209
 210 /* Generic printf-like operations.  As an extension over plain
 211    printf, these support some GDB-specific format specifiers.
 212    Particularly useful here are the styling formatters: '%p[', '%p]'
 213    and '%ps'.  See ui_out::message for details.  */
 214
 215 extern void gdb_vprintf (const char *, va_list) ATTRIBUTE_PRINTF (1, 0);
 216
 217 extern void gdb_vprintf (struct ui_file *, const char *, va_list)
 218   ATTRIBUTE_PRINTF (2, 0);
 219
 220 extern void gdb_printf (struct ui_file *, const char *, ...)
 221   ATTRIBUTE_PRINTF (2, 3);
 222
 223 extern void gdb_printf (const char *, ...) ATTRIBUTE_PRINTF (1, 2);
 224
 225 extern void printf_unfiltered (const char *, ...) ATTRIBUTE_PRINTF (1, 2);
 226
 227 extern void print_spaces (int, struct ui_file *);
 228
 229 extern const char *n_spaces (int);
 230
 231 /* Return nonzero if filtered printing is initialized.  */
 232 extern int filtered_printing_initialized (void);
 233
 234 /* Like gdb_printf, but styles the output according to STYLE,
 235    when appropriate.  */
 236
 237 extern void fprintf_styled (struct ui_file *stream,
 238                             const ui_file_style &style,
 239                             const char *fmt,
 240                             ...)
 241   ATTRIBUTE_PRINTF (3, 4);
 242
 243 /* Like gdb_puts, but styles the output according to STYLE, when
 244    appropriate.  */
 245
 246 extern void fputs_styled (const char *linebuffer,
 247                           const ui_file_style &style,
 248                           struct ui_file *stream);
 249
 250 /* Like fputs_styled, but uses highlight_style to highlight the
 251    parts of STR that match HIGHLIGHT.  */
 252
 253 extern void fputs_highlighted (const char *str, const compiled_regex &highlight,
 254                                struct ui_file *stream);
 255
 256 /* Convert CORE_ADDR to string in platform-specific manner.
 257    This is usually formatted similar to 0x%lx.  */
 258 extern const char *paddress (struct gdbarch *gdbarch, CORE_ADDR addr);
 259
 260 /* Return a string representation in hexadecimal notation of ADDRESS,
 261    which is suitable for printing.  */
 262
 263 extern const char *print_core_address (struct gdbarch *gdbarch,
 264                                        CORE_ADDR address);
 265
 266 extern CORE_ADDR string_to_core_addr (const char *my_string);
 267
 268 extern void fprintf_symbol (struct ui_file *, const char *,
 269                             enum language, int);
 270
 271 extern void perror_warning_with_name (const char *string);
 272
 273 /* Issue a warning formatted as '<filename>: <explanation>', where
 274    <filename> is FILENAME with filename styling applied.  As such, don't
 275    pass anything more than a filename in this string.  The <explanation>
 276    is a string returned from calling safe_strerror(SAVED_ERRNO).  */
 277
 278 extern void warning_filename_and_errno (const char *filename,
 279                                         int saved_errno);
 280 \f
 281 /* Warnings and error messages.  */
 282
 283 extern void (*deprecated_error_begin_hook) (void);
 284
 285 /* Message to be printed before the warning message, when a warning occurs.  */
 286
 287 extern const char *warning_pre_print;
 288
 289 extern void demangler_vwarning (const char *file, int line,
 290                                const char *, va_list ap)
 291      ATTRIBUTE_PRINTF (3, 0);
 292
 293 extern void demangler_warning (const char *file, int line,
 294                               const char *, ...) ATTRIBUTE_PRINTF (3, 4);
 295
 296 \f
 297 /* Misc. utilities.  */
 298
 299 #ifdef HAVE_WAITPID
 300 extern pid_t wait_to_die_with_timeout (pid_t pid, int *status, int timeout);
 301 #endif
 302
 303 extern int myread (int, char *, int);
 304
 305 /* Resource limits used by getrlimit and setrlimit.  */
 306
 307 enum resource_limit_kind
 308   {
 309     LIMIT_CUR,
 310     LIMIT_MAX
 311   };
 312
 313 /* Check whether GDB will be able to dump core using the dump_core
 314    function.  Returns zero if GDB cannot or should not dump core.
 315    If LIMIT_KIND is LIMIT_CUR the user's soft limit will be respected.
 316    If LIMIT_KIND is LIMIT_MAX only the hard limit will be respected.  */
 317
 318 extern int can_dump_core (enum resource_limit_kind limit_kind);
 319
 320 /* Print a warning that we cannot dump core.  */
 321
 322 extern void warn_cant_dump_core (const char *reason);
 323
 324 /* Dump core trying to increase the core soft limit to hard limit
 325    first.  */
 326
 327 extern void dump_core (void);
 328
 329 /* Copy NBITS bits from SOURCE to DEST starting at the given bit
 330    offsets.  Use the bit order as specified by BITS_BIG_ENDIAN.
 331    Source and destination buffers must not overlap.  */
 332
 333 extern void copy_bitwise (gdb_byte *dest, ULONGEST dest_offset,
 334                           const gdb_byte *source, ULONGEST source_offset,
 335                           ULONGEST nbits, int bits_big_endian);
 336
 337 /* When readline decides that the terminal cannot auto-wrap lines, it reduces
 338    the width of the reported screen width by 1.  This variable indicates
 339    whether that's the case or not, allowing us to add it back where
 340    necessary.  See _rl_term_autowrap in readline/terminal.c.  */
 341
 342 extern int readline_hidden_cols;
 343
 344 /* Assign VAL to LVAL, and set CHANGED to true if the assignment changed
 345    LVAL.  */
 346
 347 template<typename T>
 348 void
 349 assign_set_if_changed (T &lval, const T &val, bool &changed)
 350 {
 351   if (lval == val)
 352     return;
 353
 354   lval = val;
 355   changed = true;
 356 }
 357
 358 /* Assign VAL to LVAL, and return true if the assignment changed LVAL.  */
 359
 360 template<typename T>
 361 bool
 362 assign_return_if_changed (T &lval, const T &val)
 363 {
 364   if (lval == val)
 365     return false;
 366
 367   lval = val;
 368   return true;
 369 }
 370
 371 /* ARG is an argument string as passed to a GDB command which is expected
 372    to contain a single, possibly quoted, filename argument.  Extract the
 373    filename and return it as a string.  If the filename is quoted then the
 374    quotes will have been removed.  If the filename is not quoted then any
 375    escaping within the filename will have been removed.
 376
 377    If there is any content in ARG after the filename then an error will be
 378    thrown complaining about the extra content.
 379
 380    If there is no filename in ARG, or if ARG is nullptr, then an empty
 381    string will be returned.  */
 382
 383 extern std::string extract_single_filename_arg (const char *arg);
 384
 385 /* A class that can be used to intercept warnings.  A class is used
 386    here, rather than a gdb::function_view because it proved difficult
 387    to use a function view in conjunction with ATTRIBUTE_PRINTF in a
 388    way that would satisfy all compilers on all systems.  And, even
 389    though gdb only ever uses deferred_warnings here, a virtual
 390    function is used to help Insight.  */
 391 struct warning_hook_handler_type
 392 {
 393   virtual void warn (const char *format, va_list args) ATTRIBUTE_PRINTF (2, 0)
 394     = 0;
 395 };
 396
 397 typedef warning_hook_handler_type *warning_hook_handler;
 398
 399 /* Set the thread-local warning hook, and restore the old value when
 400    finished.  */
 401 class scoped_restore_warning_hook
 402 {
 403 public:
 404   explicit scoped_restore_warning_hook (warning_hook_handler new_handler);
 405
 406   ~scoped_restore_warning_hook ();
 407
 408 private:
 409   scoped_restore_warning_hook (const scoped_restore_warning_hook &other)
 410     = delete;
 411   scoped_restore_warning_hook &operator= (const scoped_restore_warning_hook &)
 412     = delete;
 413
 414   warning_hook_handler m_save;
 415 };
 416
 417 /* Return the current warning handler.  */
 418 extern warning_hook_handler get_warning_hook_handler ();
 419
 420 /* In some cases GDB needs to try several different solutions to a problem,
 421    if any of the solutions work then as far as the user is concerned the
 422    problem is solved, and GDB should continue without warnings.  However,
 423    if none of the solutions work then GDB should emit any warnings that
 424    occurred while trying each possible solution.
 425
 426    One example of this is locating separate debug info.  There are several
 427    different approaches for this; following the .gnu_debuglink, a build-id
 428    based lookup, or using debuginfod.  If any works, and debug info is
 429    located, then the user doesn't want to see warnings from the earlier
 430    approaches that were tried and failed.
 431
 432    However, GDB should emit all the warnings using separate calls to
 433    warning -- this ensures that each warning is formatted on its own line,
 434    and that any styling is emitted correctly.
 435
 436    This class helps with deferring warnings.  Warnings can be added to an
 437    instance of this class with the 'warn' function, and all warnings can be
 438    emitted with a single call to 'emit'.  */
 439
 440 struct deferred_warnings final : public warning_hook_handler_type
 441 {
 442   deferred_warnings ()
 443     : m_can_style (gdb_stderr->can_emit_style_escape ())
 444   {
 445   }
 446
 447   /* Add a warning to the list of deferred warnings.  */
 448   void warn (const char *format, ...) ATTRIBUTE_PRINTF (2, 3)
 449   {
 450     va_list args;
 451     va_start (args, format);
 452     this->warn (format, args);
 453     va_end (args);
 454   }
 455
 456   /* A variant of 'warn' so that this object can be used as a warning
 457      hook; see scoped_restore_warning_hook.  Note that no locking is
 458      done, so users have to be careful to only install this into a
 459      single thread at a time.  */
 460   void warn (const char *format, va_list args) override
 461     ATTRIBUTE_PRINTF (2, 0)
 462   {
 463     string_file msg (m_can_style);
 464     msg.vprintf (format, args);
 465     m_warnings.emplace_back (std::move (msg));
 466   }
 467
 468   /* Emit all warnings.  */
 469   void emit () const
 470   {
 471     for (const auto &w : m_warnings)
 472       warning ("%s", w.c_str ());
 473   }
 474
 475 private:
 476
 477   /* True if gdb_stderr supports styling at the moment this object is
 478      constructed.  This is done just once so that objects of this type
 479      can be used off the main thread.  */
 480   bool m_can_style;
 481
 482   /* The list of all deferred warnings.  */
 483   std::vector<string_file> m_warnings;
 484 };
 485
 486 #endif /* GDB_UTILS_H */