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