gdb/utils.h

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