gdb/utils.h

   1 /* *INDENT-OFF* */ /* ATTRIBUTE_PRINTF confuses indent, avoid running it
   2                       for now.  */
   3 /* I/O, string, cleanup, and other random utilities for GDB.
   4    Copyright (C) 1986-2018 Free Software Foundation, Inc.
   5
   6    This file is part of GDB.
   7
   8    This program is free software; you can redistribute it and/or modify
   9    it under the terms of the GNU General Public License as published by
  10    the Free Software Foundation; either version 3 of the License, or
  11    (at your option) any later version.
  12
  13    This program is distributed in the hope that it will be useful,
  14    but WITHOUT ANY WARRANTY; without even the implied warranty of
  15    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  16    GNU General Public License for more details.
  17
  18    You should have received a copy of the GNU General Public License
  19    along with this program.  If not, see <http://www.gnu.org/licenses/>.  */
  20
  21 #ifndef UTILS_H
  22 #define UTILS_H
  23
  24 #include "exceptions.h"
  25 #include "common/scoped_restore.h"
  26 #include <chrono>
  27
  28 extern void initialize_utils (void);
  29
  30 /* String utilities.  */
  31
  32 extern int 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).  */
  61 extern int strncmp_iw_with_mode
  62   (const char *string1, const char *string2, size_t string2_len,
  63    strncmp_iw_mode mode, enum language language,
  64    completion_match_for_lcd *match_for_lcd = NULL);
  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 /* Return true if the strings are equal.  */
  93
  94 extern bool streq (const char *, const char *);
  95
  96 /* A variant of streq that is suitable for use as an htab
  97    callback.  */
  98
  99 extern int streq_hash (const void *, const void *);
 100
 101 extern int subset_compare (const char *, const char *);
 102
 103 int compare_positive_ints (const void *ap, const void *bp);
 104 int compare_strings (const void *ap, const void *bp);
 105
 106 /* Compare C strings for std::sort.  */
 107
 108 static inline bool
 109 compare_cstrings (const char *str1, const char *str2)
 110 {
 111   return strcmp (str1, str2) < 0;
 112 }
 113
 114 /* A wrapper for bfd_errmsg to produce a more helpful error message
 115    in the case of bfd_error_file_ambiguously recognized.
 116    MATCHING, if non-NULL, is the corresponding argument to
 117    bfd_check_format_matches, and will be freed.  */
 118
 119 extern const char *gdb_bfd_errmsg (bfd_error_type error_tag, char **matching);
 120
 121 /* Reset the prompt_for_continue clock.  */
 122 void reset_prompt_for_continue_wait_time (void);
 123 /* Return the time spent in prompt_for_continue.  */
 124 std::chrono::steady_clock::duration get_prompt_for_continue_wait_time ();
 125 \f
 126 /* Parsing utilites.  */
 127
 128 extern int parse_pid_to_attach (const char *args);
 129
 130 extern int parse_escape (struct gdbarch *, const char **);
 131
 132 /* A wrapper for an array of char* that was allocated in the way that
 133    'buildargv' does, and should be freed with 'freeargv'.  */
 134
 135 class gdb_argv
 136 {
 137 public:
 138
 139   /* A constructor that initializes to NULL.  */
 140
 141   gdb_argv ()
 142     : m_argv (NULL)
 143   {
 144   }
 145
 146   /* A constructor that calls buildargv on STR.  STR may be NULL, in
 147      which case this object is initialized with a NULL array.  If
 148      buildargv fails due to out-of-memory, call malloc_failure.
 149      Therefore, the value is guaranteed to be non-NULL, unless the
 150      parameter itself is NULL.  */
 151
 152   explicit gdb_argv (const char *str)
 153     : m_argv (NULL)
 154   {
 155     reset (str);
 156   }
 157
 158   /* A constructor that takes ownership of an existing array.  */
 159
 160   explicit gdb_argv (char **array)
 161     : m_argv (array)
 162   {
 163   }
 164
 165   gdb_argv (const gdb_argv &) = delete;
 166   gdb_argv &operator= (const gdb_argv &) = delete;
 167
 168   ~gdb_argv ()
 169   {
 170     freeargv (m_argv);
 171   }
 172
 173   /* Call buildargv on STR, storing the result in this object.  Any
 174      previous state is freed.  STR may be NULL, in which case this
 175      object is reset with a NULL array.  If buildargv fails due to
 176      out-of-memory, call malloc_failure.  Therefore, the value is
 177      guaranteed to be non-NULL, unless the parameter itself is
 178      NULL.  */
 179
 180   void reset (const char *str);
 181
 182   /* Return the underlying array.  */
 183
 184   char **get ()
 185   {
 186     return m_argv;
 187   }
 188
 189   /* Return the underlying array, transferring ownership to the
 190      caller.  */
 191
 192   char **release ()
 193   {
 194     char **result = m_argv;
 195     m_argv = NULL;
 196     return result;
 197   }
 198
 199   /* Return the number of items in the array.  */
 200
 201   int count () const
 202   {
 203     return countargv (m_argv);
 204   }
 205
 206   /* Index into the array.  */
 207
 208   char *operator[] (int arg)
 209   {
 210     gdb_assert (m_argv != NULL);
 211     return m_argv[arg];
 212   }
 213
 214   /* The iterator type.  */
 215
 216   typedef char **iterator;
 217
 218   /* Return an iterator pointing to the start of the array.  */
 219
 220   iterator begin ()
 221   {
 222     return m_argv;
 223   }
 224
 225   /* Return an iterator pointing to the end of the array.  */
 226
 227   iterator end ()
 228   {
 229     return m_argv + count ();
 230   }
 231
 232   bool operator!= (std::nullptr_t)
 233   {
 234     return m_argv != NULL;
 235   }
 236
 237   bool operator== (std::nullptr_t)
 238   {
 239     return m_argv == NULL;
 240   }
 241
 242 private:
 243
 244   /* The wrapped array.  */
 245
 246   char **m_argv;
 247 };
 248
 249 \f
 250 /* Cleanup utilities.  */
 251
 252 /* For make_cleanup_close see common/filestuff.h.  */
 253
 254 extern struct cleanup *make_cleanup_value_free_to_mark (struct value *);
 255
 256 /* A deleter for a hash table.  */
 257 struct htab_deleter
 258 {
 259   void operator() (htab *ptr) const
 260   {
 261     htab_delete (ptr);
 262   }
 263 };
 264
 265 /* A unique_ptr wrapper for htab_t.  */
 266 typedef std::unique_ptr<htab, htab_deleter> htab_up;
 267
 268 extern void free_current_contents (void *);
 269
 270 extern void init_page_info (void);
 271
 272 /* Temporarily set BATCH_FLAG and the associated unlimited terminal size.
 273    Restore when destroyed.  */
 274
 275 struct set_batch_flag_and_restore_page_info
 276 {
 277 public:
 278
 279   set_batch_flag_and_restore_page_info ();
 280   ~set_batch_flag_and_restore_page_info ();
 281
 282   DISABLE_COPY_AND_ASSIGN (set_batch_flag_and_restore_page_info);
 283
 284 private:
 285
 286   /* Note that this doesn't use scoped_restore, because it's important
 287      to control the ordering of operations in the destruction, and it
 288      was simpler to avoid introducing a new ad hoc class.  */
 289   unsigned m_save_lines_per_page;
 290   unsigned m_save_chars_per_line;
 291   int m_save_batch_flag;
 292 };
 293
 294 extern struct cleanup *make_bpstat_clear_actions_cleanup (void);
 295 \f
 296 /* Path utilities.  */
 297
 298 extern int gdb_filename_fnmatch (const char *pattern, const char *string,
 299                                  int flags);
 300
 301 extern void substitute_path_component (char **stringp, const char *from,
 302                                        const char *to);
 303
 304 std::string ldirname (const char *filename);
 305
 306 extern int count_path_elements (const char *path);
 307
 308 extern const char *strip_leading_path_elements (const char *path, int n);
 309 \f
 310 /* GDB output, ui_file utilities.  */
 311
 312 struct ui_file;
 313
 314 extern int query (const char *, ...) ATTRIBUTE_PRINTF (1, 2);
 315 extern int nquery (const char *, ...) ATTRIBUTE_PRINTF (1, 2);
 316 extern int yquery (const char *, ...) ATTRIBUTE_PRINTF (1, 2);
 317
 318 extern void begin_line (void);
 319
 320 extern void wrap_here (const char *);
 321
 322 extern void reinitialize_more_filter (void);
 323
 324 extern int pagination_enabled;
 325
 326 extern struct ui_file **current_ui_gdb_stdout_ptr (void);
 327 extern struct ui_file **current_ui_gdb_stdin_ptr (void);
 328 extern struct ui_file **current_ui_gdb_stderr_ptr (void);
 329 extern struct ui_file **current_ui_gdb_stdlog_ptr (void);
 330
 331 /* The current top level's ui_file streams.  */
 332
 333 /* Normal results */
 334 #define gdb_stdout (*current_ui_gdb_stdout_ptr ())
 335 /* Input stream */
 336 #define gdb_stdin (*current_ui_gdb_stdin_ptr ())
 337 /* Serious error notifications */
 338 #define gdb_stderr (*current_ui_gdb_stderr_ptr ())
 339 /* Log/debug/trace messages that should bypass normal stdout/stderr
 340    filtering.  For moment, always call this stream using
 341    *_unfiltered.  In the very near future that restriction shall be
 342    removed - either call shall be unfiltered.  (cagney 1999-06-13).  */
 343 #define gdb_stdlog (*current_ui_gdb_stdlog_ptr ())
 344
 345 /* Truly global ui_file streams.  These are all defined in main.c.  */
 346
 347 /* Target output that should bypass normal stdout/stderr filtering.
 348    For moment, always call this stream using *_unfiltered.  In the
 349    very near future that restriction shall be removed - either call
 350    shall be unfiltered.  (cagney 1999-07-02).  */
 351 extern struct ui_file *gdb_stdtarg;
 352 extern struct ui_file *gdb_stdtargerr;
 353 extern struct ui_file *gdb_stdtargin;
 354
 355 /* Set the screen dimensions to WIDTH and HEIGHT.  */
 356
 357 extern void set_screen_width_and_height (int width, int height);
 358
 359 /* More generic printf like operations.  Filtered versions may return
 360    non-locally on error.  */
 361
 362 extern void fputs_filtered (const char *, struct ui_file *);
 363
 364 extern void fputs_unfiltered (const char *, struct ui_file *);
 365
 366 extern int fputc_filtered (int c, struct ui_file *);
 367
 368 extern int fputc_unfiltered (int c, struct ui_file *);
 369
 370 extern int putchar_filtered (int c);
 371
 372 extern int putchar_unfiltered (int c);
 373
 374 extern void puts_filtered (const char *);
 375
 376 extern void puts_unfiltered (const char *);
 377
 378 extern void puts_filtered_tabular (char *string, int width, int right);
 379
 380 extern void puts_debug (char *prefix, char *string, char *suffix);
 381
 382 extern void vprintf_filtered (const char *, va_list) ATTRIBUTE_PRINTF (1, 0);
 383
 384 extern void vfprintf_filtered (struct ui_file *, const char *, va_list)
 385   ATTRIBUTE_PRINTF (2, 0);
 386
 387 extern void fprintf_filtered (struct ui_file *, const char *, ...)
 388   ATTRIBUTE_PRINTF (2, 3);
 389
 390 extern void fprintfi_filtered (int, struct ui_file *, const char *, ...)
 391   ATTRIBUTE_PRINTF (3, 4);
 392
 393 extern void printf_filtered (const char *, ...) ATTRIBUTE_PRINTF (1, 2);
 394
 395 extern void printfi_filtered (int, const char *, ...) ATTRIBUTE_PRINTF (2, 3);
 396
 397 extern void vprintf_unfiltered (const char *, va_list) ATTRIBUTE_PRINTF (1, 0);
 398
 399 extern void vfprintf_unfiltered (struct ui_file *, const char *, va_list)
 400   ATTRIBUTE_PRINTF (2, 0);
 401
 402 extern void fprintf_unfiltered (struct ui_file *, const char *, ...)
 403   ATTRIBUTE_PRINTF (2, 3);
 404
 405 extern void printf_unfiltered (const char *, ...) ATTRIBUTE_PRINTF (1, 2);
 406
 407 extern void print_spaces (int, struct ui_file *);
 408
 409 extern void print_spaces_filtered (int, struct ui_file *);
 410
 411 extern char *n_spaces (int);
 412
 413 extern void fputstr_filtered (const char *str, int quotr,
 414                               struct ui_file * stream);
 415
 416 extern void fputstr_unfiltered (const char *str, int quotr,
 417                                 struct ui_file * stream);
 418
 419 extern void fputstrn_filtered (const char *str, int n, int quotr,
 420                                struct ui_file * stream);
 421
 422 extern void fputstrn_unfiltered (const char *str, int n, int quotr,
 423                                  struct ui_file * stream);
 424
 425 /* Return nonzero if filtered printing is initialized.  */
 426 extern int filtered_printing_initialized (void);
 427
 428 /* Display the host ADDR on STREAM formatted as ``0x%x''.  */
 429 extern void gdb_print_host_address_1 (const void *addr, struct ui_file *stream);
 430
 431 /* Wrapper that avoids adding a pointless cast to all callers.  */
 432 #define gdb_print_host_address(ADDR, STREAM) \
 433   gdb_print_host_address_1 ((const void *) ADDR, STREAM)
 434
 435 /* Return the address only having significant bits.  */
 436 extern CORE_ADDR address_significant (gdbarch *gdbarch, CORE_ADDR addr);
 437
 438 /* Convert CORE_ADDR to string in platform-specific manner.
 439    This is usually formatted similar to 0x%lx.  */
 440 extern const char *paddress (struct gdbarch *gdbarch, CORE_ADDR addr);
 441
 442 /* Return a string representation in hexadecimal notation of ADDRESS,
 443    which is suitable for printing.  */
 444
 445 extern const char *print_core_address (struct gdbarch *gdbarch,
 446                                        CORE_ADDR address);
 447
 448 /* Callback hash_f and eq_f for htab_create_alloc or htab_create_alloc_ex.  */
 449 extern hashval_t core_addr_hash (const void *ap);
 450 extern int core_addr_eq (const void *ap, const void *bp);
 451
 452 extern CORE_ADDR string_to_core_addr (const char *my_string);
 453
 454 extern void fprintf_symbol_filtered (struct ui_file *, const char *,
 455                                      enum language, int);
 456
 457 extern void throw_perror_with_name (enum errors errcode, const char *string)
 458   ATTRIBUTE_NORETURN;
 459
 460 extern void perror_warning_with_name (const char *string);
 461
 462 extern void print_sys_errmsg (const char *, int);
 463 \f
 464 /* Warnings and error messages.  */
 465
 466 extern void (*deprecated_error_begin_hook) (void);
 467
 468 /* Message to be printed before the warning message, when a warning occurs.  */
 469
 470 extern const char *warning_pre_print;
 471
 472 extern void error_stream (const string_file &) ATTRIBUTE_NORETURN;
 473
 474 extern void demangler_vwarning (const char *file, int line,
 475                                const char *, va_list ap)
 476      ATTRIBUTE_PRINTF (3, 0);
 477
 478 extern void demangler_warning (const char *file, int line,
 479                               const char *, ...) ATTRIBUTE_PRINTF (3, 4);
 480
 481 \f
 482 /* Misc. utilities.  */
 483
 484 /* Allocation and deallocation functions for the libiberty hash table
 485    which use obstacks.  */
 486 void *hashtab_obstack_allocate (void *data, size_t size, size_t count);
 487 void dummy_obstack_deallocate (void *object, void *data);
 488
 489 #ifdef HAVE_WAITPID
 490 extern pid_t wait_to_die_with_timeout (pid_t pid, int *status, int timeout);
 491 #endif
 492
 493 extern int myread (int, char *, int);
 494
 495 /* Ensure that V is aligned to an N byte boundary (B's assumed to be a
 496    power of 2).  Round up/down when necessary.  Examples of correct
 497    use include:
 498
 499    addr = align_up (addr, 8); -- VALUE needs 8 byte alignment
 500    write_memory (addr, value, len);
 501    addr += len;
 502
 503    and:
 504
 505    sp = align_down (sp - len, 16); -- Keep SP 16 byte aligned
 506    write_memory (sp, value, len);
 507
 508    Note that uses such as:
 509
 510    write_memory (addr, value, len);
 511    addr += align_up (len, 8);
 512
 513    and:
 514
 515    sp -= align_up (len, 8);
 516    write_memory (sp, value, len);
 517
 518    are typically not correct as they don't ensure that the address (SP
 519    or ADDR) is correctly aligned (relying on previous alignment to
 520    keep things right).  This is also why the methods are called
 521    "align_..." instead of "round_..." as the latter reads better with
 522    this incorrect coding style.  */
 523
 524 extern ULONGEST align_up (ULONGEST v, int n);
 525 extern ULONGEST align_down (ULONGEST v, int n);
 526
 527 /* Resource limits used by getrlimit and setrlimit.  */
 528
 529 enum resource_limit_kind
 530   {
 531     LIMIT_CUR,
 532     LIMIT_MAX
 533   };
 534
 535 /* Check whether GDB will be able to dump core using the dump_core
 536    function.  Returns zero if GDB cannot or should not dump core.
 537    If LIMIT_KIND is LIMIT_CUR the user's soft limit will be respected.
 538    If LIMIT_KIND is LIMIT_MAX only the hard limit will be respected.  */
 539
 540 extern int can_dump_core (enum resource_limit_kind limit_kind);
 541
 542 /* Print a warning that we cannot dump core.  */
 543
 544 extern void warn_cant_dump_core (const char *reason);
 545
 546 /* Dump core trying to increase the core soft limit to hard limit
 547    first.  */
 548
 549 extern void dump_core (void);
 550
 551 /* Return the hex string form of LENGTH bytes of DATA.
 552    Space for the result is malloc'd, caller must free.  */
 553
 554 extern char *make_hex_string (const gdb_byte *data, size_t length);
 555
 556 #endif /* UTILS_H */