Remove make_cleanup_free_section_addr_info
[external/binutils.git] / 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 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 int gdb_filename_fnmatch (const char *pattern, const char *string,
295                                  int flags);
296
297 extern void substitute_path_component (char **stringp, const char *from,
298                                        const char *to);
299
300 std::string ldirname (const char *filename);
301
302 extern int count_path_elements (const char *path);
303
304 extern const char *strip_leading_path_elements (const char *path, int n);
305 \f
306 /* GDB output, ui_file utilities.  */
307
308 struct ui_file;
309
310 extern int query (const char *, ...) ATTRIBUTE_PRINTF (1, 2);
311 extern int nquery (const char *, ...) ATTRIBUTE_PRINTF (1, 2);
312 extern int yquery (const char *, ...) ATTRIBUTE_PRINTF (1, 2);
313
314 extern void begin_line (void);
315
316 extern void wrap_here (const char *);
317
318 extern void reinitialize_more_filter (void);
319
320 extern int pagination_enabled;
321
322 extern struct ui_file **current_ui_gdb_stdout_ptr (void);
323 extern struct ui_file **current_ui_gdb_stdin_ptr (void);
324 extern struct ui_file **current_ui_gdb_stderr_ptr (void);
325 extern struct ui_file **current_ui_gdb_stdlog_ptr (void);
326
327 /* The current top level's ui_file streams.  */
328
329 /* Normal results */
330 #define gdb_stdout (*current_ui_gdb_stdout_ptr ())
331 /* Input stream */
332 #define gdb_stdin (*current_ui_gdb_stdin_ptr ())
333 /* Serious error notifications */
334 #define gdb_stderr (*current_ui_gdb_stderr_ptr ())
335 /* Log/debug/trace messages that should bypass normal stdout/stderr
336    filtering.  For moment, always call this stream using
337    *_unfiltered.  In the very near future that restriction shall be
338    removed - either call shall be unfiltered.  (cagney 1999-06-13).  */
339 #define gdb_stdlog (*current_ui_gdb_stdlog_ptr ())
340
341 /* Truly global ui_file streams.  These are all defined in main.c.  */
342
343 /* Target output that should bypass normal stdout/stderr filtering.
344    For moment, always call this stream using *_unfiltered.  In the
345    very near future that restriction shall be removed - either call
346    shall be unfiltered.  (cagney 1999-07-02).  */
347 extern struct ui_file *gdb_stdtarg;
348 extern struct ui_file *gdb_stdtargerr;
349 extern struct ui_file *gdb_stdtargin;
350
351 /* Set the screen dimensions to WIDTH and HEIGHT.  */
352
353 extern void set_screen_width_and_height (int width, int height);
354
355 /* More generic printf like operations.  Filtered versions may return
356    non-locally on error.  */
357
358 extern void fputs_filtered (const char *, struct ui_file *);
359
360 extern void fputs_unfiltered (const char *, struct ui_file *);
361
362 extern int fputc_filtered (int c, struct ui_file *);
363
364 extern int fputc_unfiltered (int c, struct ui_file *);
365
366 extern int putchar_filtered (int c);
367
368 extern int putchar_unfiltered (int c);
369
370 extern void puts_filtered (const char *);
371
372 extern void puts_unfiltered (const char *);
373
374 extern void puts_filtered_tabular (char *string, int width, int right);
375
376 extern void puts_debug (char *prefix, char *string, char *suffix);
377
378 extern void vprintf_filtered (const char *, va_list) ATTRIBUTE_PRINTF (1, 0);
379
380 extern void vfprintf_filtered (struct ui_file *, const char *, va_list)
381   ATTRIBUTE_PRINTF (2, 0);
382
383 extern void fprintf_filtered (struct ui_file *, const char *, ...)
384   ATTRIBUTE_PRINTF (2, 3);
385
386 extern void fprintfi_filtered (int, struct ui_file *, const char *, ...)
387   ATTRIBUTE_PRINTF (3, 4);
388
389 extern void printf_filtered (const char *, ...) ATTRIBUTE_PRINTF (1, 2);
390
391 extern void printfi_filtered (int, const char *, ...) ATTRIBUTE_PRINTF (2, 3);
392
393 extern void vprintf_unfiltered (const char *, va_list) ATTRIBUTE_PRINTF (1, 0);
394
395 extern void vfprintf_unfiltered (struct ui_file *, const char *, va_list)
396   ATTRIBUTE_PRINTF (2, 0);
397
398 extern void fprintf_unfiltered (struct ui_file *, const char *, ...)
399   ATTRIBUTE_PRINTF (2, 3);
400
401 extern void printf_unfiltered (const char *, ...) ATTRIBUTE_PRINTF (1, 2);
402
403 extern void print_spaces (int, struct ui_file *);
404
405 extern void print_spaces_filtered (int, struct ui_file *);
406
407 extern char *n_spaces (int);
408
409 extern void fputstr_filtered (const char *str, int quotr,
410                               struct ui_file * stream);
411
412 extern void fputstr_unfiltered (const char *str, int quotr,
413                                 struct ui_file * stream);
414
415 extern void fputstrn_filtered (const char *str, int n, int quotr,
416                                struct ui_file * stream);
417
418 extern void fputstrn_unfiltered (const char *str, int n, int quotr,
419                                  struct ui_file * stream);
420
421 /* Return nonzero if filtered printing is initialized.  */
422 extern int filtered_printing_initialized (void);
423
424 /* Display the host ADDR on STREAM formatted as ``0x%x''.  */
425 extern void gdb_print_host_address_1 (const void *addr, struct ui_file *stream);
426
427 /* Wrapper that avoids adding a pointless cast to all callers.  */
428 #define gdb_print_host_address(ADDR, STREAM) \
429   gdb_print_host_address_1 ((const void *) ADDR, STREAM)
430
431 /* Return the address only having significant bits.  */
432 extern CORE_ADDR address_significant (gdbarch *gdbarch, CORE_ADDR addr);
433
434 /* Convert CORE_ADDR to string in platform-specific manner.
435    This is usually formatted similar to 0x%lx.  */
436 extern const char *paddress (struct gdbarch *gdbarch, CORE_ADDR addr);
437
438 /* Return a string representation in hexadecimal notation of ADDRESS,
439    which is suitable for printing.  */
440
441 extern const char *print_core_address (struct gdbarch *gdbarch,
442                                        CORE_ADDR address);
443
444 /* Callback hash_f and eq_f for htab_create_alloc or htab_create_alloc_ex.  */
445 extern hashval_t core_addr_hash (const void *ap);
446 extern int core_addr_eq (const void *ap, const void *bp);
447
448 extern CORE_ADDR string_to_core_addr (const char *my_string);
449
450 extern void fprintf_symbol_filtered (struct ui_file *, const char *,
451                                      enum language, int);
452
453 extern void throw_perror_with_name (enum errors errcode, const char *string)
454   ATTRIBUTE_NORETURN;
455
456 extern void perror_warning_with_name (const char *string);
457
458 extern void print_sys_errmsg (const char *, int);
459 \f
460 /* Warnings and error messages.  */
461
462 extern void (*deprecated_error_begin_hook) (void);
463
464 /* Message to be printed before the warning message, when a warning occurs.  */
465
466 extern const char *warning_pre_print;
467
468 extern void error_stream (const string_file &) ATTRIBUTE_NORETURN;
469
470 extern void demangler_vwarning (const char *file, int line,
471                                const char *, va_list ap)
472      ATTRIBUTE_PRINTF (3, 0);
473
474 extern void demangler_warning (const char *file, int line,
475                               const char *, ...) ATTRIBUTE_PRINTF (3, 4);
476
477 \f
478 /* Misc. utilities.  */
479
480 /* Allocation and deallocation functions for the libiberty hash table
481    which use obstacks.  */
482 void *hashtab_obstack_allocate (void *data, size_t size, size_t count);
483 void dummy_obstack_deallocate (void *object, void *data);
484
485 #ifdef HAVE_WAITPID
486 extern pid_t wait_to_die_with_timeout (pid_t pid, int *status, int timeout);
487 #endif
488
489 extern int myread (int, char *, int);
490
491 /* Ensure that V is aligned to an N byte boundary (B's assumed to be a
492    power of 2).  Round up/down when necessary.  Examples of correct
493    use include:
494
495    addr = align_up (addr, 8); -- VALUE needs 8 byte alignment
496    write_memory (addr, value, len);
497    addr += len;
498
499    and:
500
501    sp = align_down (sp - len, 16); -- Keep SP 16 byte aligned
502    write_memory (sp, value, len);
503
504    Note that uses such as:
505
506    write_memory (addr, value, len);
507    addr += align_up (len, 8);
508
509    and:
510
511    sp -= align_up (len, 8);
512    write_memory (sp, value, len);
513
514    are typically not correct as they don't ensure that the address (SP
515    or ADDR) is correctly aligned (relying on previous alignment to
516    keep things right).  This is also why the methods are called
517    "align_..." instead of "round_..." as the latter reads better with
518    this incorrect coding style.  */
519
520 extern ULONGEST align_up (ULONGEST v, int n);
521 extern ULONGEST align_down (ULONGEST v, int n);
522
523 /* Resource limits used by getrlimit and setrlimit.  */
524
525 enum resource_limit_kind
526   {
527     LIMIT_CUR,
528     LIMIT_MAX
529   };
530
531 /* Check whether GDB will be able to dump core using the dump_core
532    function.  Returns zero if GDB cannot or should not dump core.
533    If LIMIT_KIND is LIMIT_CUR the user's soft limit will be respected.
534    If LIMIT_KIND is LIMIT_MAX only the hard limit will be respected.  */
535
536 extern int can_dump_core (enum resource_limit_kind limit_kind);
537
538 /* Print a warning that we cannot dump core.  */
539
540 extern void warn_cant_dump_core (const char *reason);
541
542 /* Dump core trying to increase the core soft limit to hard limit
543    first.  */
544
545 extern void dump_core (void);
546
547 /* Return the hex string form of LENGTH bytes of DATA.
548    Space for the result is malloc'd, caller must free.  */
549
550 extern char *make_hex_string (const gdb_byte *data, size_t length);
551
552 #endif /* UTILS_H */