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