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