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 std::string ldirname (const char *filename);
 140
 141 extern int count_path_elements (const char *path);
 142
 143 extern const char *strip_leading_path_elements (const char *path, int n);
 144 \f
 145 /* GDB output, ui_file utilities.  */
 146
 147 struct ui_file;
 148
 149 extern int query (const char *, ...) ATTRIBUTE_PRINTF (1, 2);
 150 extern int nquery (const char *, ...) ATTRIBUTE_PRINTF (1, 2);
 151 extern int yquery (const char *, ...) ATTRIBUTE_PRINTF (1, 2);
 152
 153 extern void begin_line (void);
 154
 155 extern void wrap_here (int);
 156
 157 extern void reinitialize_more_filter (void);
 158
 159 /* Return the number of characters in a line.  */
 160
 161 extern int get_chars_per_line ();
 162
 163 extern bool pagination_enabled;
 164
 165 /* A flag indicating whether to timestamp debugging messages.  */
 166 extern bool debug_timestamp;
 167
 168 extern struct ui_file **current_ui_gdb_stdout_ptr (void);
 169 extern struct ui_file **current_ui_gdb_stdin_ptr (void);
 170 extern struct ui_file **current_ui_gdb_stderr_ptr (void);
 171 extern struct ui_file **current_ui_gdb_stdlog_ptr (void);
 172
 173 /* Flush STREAM.  */
 174 extern void gdb_flush (struct ui_file *stream);
 175
 176 /* The current top level's ui_file streams.  */
 177
 178 /* Normal results */
 179 #define gdb_stdout (*current_ui_gdb_stdout_ptr ())
 180 /* Input stream */
 181 #define gdb_stdin (*current_ui_gdb_stdin_ptr ())
 182 /* Serious error notifications.  This bypasses the pager, if one is in
 183    use.  */
 184 #define gdb_stderr (*current_ui_gdb_stderr_ptr ())
 185 /* Log/debug/trace messages that bypasses the pager, if one is in
 186    use.  */
 187 #define gdb_stdlog (*current_ui_gdb_stdlog_ptr ())
 188
 189 /* Truly global ui_file streams.  These are all defined in main.c.  */
 190
 191 /* Target output that should bypass the pager, if one is in use.  */
 192 extern struct ui_file *gdb_stdtarg;
 193 extern struct ui_file *gdb_stdtargerr;
 194 extern struct ui_file *gdb_stdtargin;
 195
 196 /* Set the screen dimensions to WIDTH and HEIGHT.  */
 197
 198 extern void set_screen_width_and_height (int width, int height);
 199
 200 /* Generic stdio-like operations.  */
 201
 202 extern void gdb_puts (const char *, struct ui_file *);
 203
 204 extern void gdb_putc (int c, struct ui_file *);
 205
 206 extern void gdb_putc (int c);
 207
 208 extern void gdb_puts (const char *);
 209
 210 extern void puts_tabular (char *string, int width, int right);
 211
 212 /* Generic printf-like operations.  As an extension over plain
 213    printf, these support some GDB-specific format specifiers.
 214    Particularly useful here are the styling formatters: '%p[', '%p]'
 215    and '%ps'.  See ui_out::message for details.  */
 216
 217 extern void gdb_vprintf (const char *, va_list) ATTRIBUTE_PRINTF (1, 0);
 218
 219 extern void gdb_vprintf (struct ui_file *, const char *, va_list)
 220   ATTRIBUTE_PRINTF (2, 0);
 221
 222 extern void gdb_printf (struct ui_file *, const char *, ...)
 223   ATTRIBUTE_PRINTF (2, 3);
 224
 225 extern void gdb_printf (const char *, ...) ATTRIBUTE_PRINTF (1, 2);
 226
 227 extern void printf_unfiltered (const char *, ...) ATTRIBUTE_PRINTF (1, 2);
 228
 229 extern void print_spaces (int, struct ui_file *);
 230
 231 extern const char *n_spaces (int);
 232
 233 /* Return nonzero if filtered printing is initialized.  */
 234 extern int filtered_printing_initialized (void);
 235
 236 /* Like gdb_printf, but styles the output according to STYLE,
 237    when appropriate.  */
 238
 239 extern void fprintf_styled (struct ui_file *stream,
 240                             const ui_file_style &style,
 241                             const char *fmt,
 242                             ...)
 243   ATTRIBUTE_PRINTF (3, 4);
 244
 245 /* Like gdb_puts, but styles the output according to STYLE, when
 246    appropriate.  */
 247
 248 extern void fputs_styled (const char *linebuffer,
 249                           const ui_file_style &style,
 250                           struct ui_file *stream);
 251
 252 /* Like fputs_styled, but uses highlight_style to highlight the
 253    parts of STR that match HIGHLIGHT.  */
 254
 255 extern void fputs_highlighted (const char *str, const compiled_regex &highlight,
 256                                struct ui_file *stream);
 257
 258 /* Convert CORE_ADDR to string in platform-specific manner.
 259    This is usually formatted similar to 0x%lx.  */
 260 extern const char *paddress (struct gdbarch *gdbarch, CORE_ADDR addr);
 261
 262 /* Return a string representation in hexadecimal notation of ADDRESS,
 263    which is suitable for printing.  */
 264
 265 extern const char *print_core_address (struct gdbarch *gdbarch,
 266                                        CORE_ADDR address);
 267
 268 extern CORE_ADDR string_to_core_addr (const char *my_string);
 269
 270 extern void fprintf_symbol (struct ui_file *, const char *,
 271                             enum language, int);
 272
 273 extern void perror_warning_with_name (const char *string);
 274
 275 extern void print_sys_errmsg (const char *, int);
 276 \f
 277 /* Warnings and error messages.  */
 278
 279 extern void (*deprecated_error_begin_hook) (void);
 280
 281 /* Message to be printed before the warning message, when a warning occurs.  */
 282
 283 extern const char *warning_pre_print;
 284
 285 extern void demangler_vwarning (const char *file, int line,
 286                                const char *, va_list ap)
 287      ATTRIBUTE_PRINTF (3, 0);
 288
 289 extern void demangler_warning (const char *file, int line,
 290                               const char *, ...) ATTRIBUTE_PRINTF (3, 4);
 291
 292 \f
 293 /* Misc. utilities.  */
 294
 295 #ifdef HAVE_WAITPID
 296 extern pid_t wait_to_die_with_timeout (pid_t pid, int *status, int timeout);
 297 #endif
 298
 299 extern int myread (int, char *, int);
 300
 301 /* Resource limits used by getrlimit and setrlimit.  */
 302
 303 enum resource_limit_kind
 304   {
 305     LIMIT_CUR,
 306     LIMIT_MAX
 307   };
 308
 309 /* Check whether GDB will be able to dump core using the dump_core
 310    function.  Returns zero if GDB cannot or should not dump core.
 311    If LIMIT_KIND is LIMIT_CUR the user's soft limit will be respected.
 312    If LIMIT_KIND is LIMIT_MAX only the hard limit will be respected.  */
 313
 314 extern int can_dump_core (enum resource_limit_kind limit_kind);
 315
 316 /* Print a warning that we cannot dump core.  */
 317
 318 extern void warn_cant_dump_core (const char *reason);
 319
 320 /* Dump core trying to increase the core soft limit to hard limit
 321    first.  */
 322
 323 extern void dump_core (void);
 324
 325 /* Copy NBITS bits from SOURCE to DEST starting at the given bit
 326    offsets.  Use the bit order as specified by BITS_BIG_ENDIAN.
 327    Source and destination buffers must not overlap.  */
 328
 329 extern void copy_bitwise (gdb_byte *dest, ULONGEST dest_offset,
 330                           const gdb_byte *source, ULONGEST source_offset,
 331                           ULONGEST nbits, int bits_big_endian);
 332
 333 /* When readline decides that the terminal cannot auto-wrap lines, it reduces
 334    the width of the reported screen width by 1.  This variable indicates
 335    whether that's the case or not, allowing us to add it back where
 336    necessary.  See _rl_term_autowrap in readline/terminal.c.  */
 337
 338 extern int readline_hidden_cols;
 339
 340 #endif /* UTILS_H */