GDB (xrefs)
Loading...
Searching...
No Matches
utils.h
Go to the documentation of this file.
1/* I/O, string, cleanup, and other random utilities for GDB.
2 Copyright (C) 1986-2023 Free Software Foundation, Inc.
3
4 This file is part of GDB.
5
6 This program is free software; you can redistribute it and/or modify
7 it under the terms of the GNU General Public License as published by
8 the Free Software Foundation; either version 3 of the License, or
9 (at your option) any later version.
10
11 This program is distributed in the hope that it will be useful,
12 but WITHOUT ANY WARRANTY; without even the implied warranty of
13 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
14 GNU General Public License for more details.
15
16 You should have received a copy of the GNU General Public License
17 along with this program. If not, see <http://www.gnu.org/licenses/>. */
18
19#ifndef UTILS_H
20#define UTILS_H
21
22#include "exceptions.h"
23#include "gdbsupport/array-view.h"
24#include "gdbsupport/scoped_restore.h"
25#include <chrono>
26
28class compiled_regex;
29
30/* String utilities. */
31
32extern bool sevenbit_strings;
33
34/* Modes of operation for strncmp_iw_with_mode. */
35
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". */
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). If IGNORE_TEMPLATE_PARAMS is true, all template
61 parameter lists will be ignored when language is C++. */
62
63extern int strncmp_iw_with_mode
64 (const char *string1, const char *string2, size_t string2_len,
66 completion_match_for_lcd *match_for_lcd = NULL,
67 bool ignore_template_params = false);
68
69/* Do a strncmp() type operation on STRING1 and STRING2, ignoring any
70 differences in whitespace. STRING2_LEN is STRING2's length.
71 Returns 0 if STRING1 matches STRING2_LEN characters of STRING2,
72 non-zero otherwise (slightly different than strncmp()'s range of
73 return values). Note: passes language_minimal to
74 strncmp_iw_with_mode, and should therefore be avoided if a more
75 suitable language is available. */
76extern int strncmp_iw (const char *string1, const char *string2,
77 size_t string2_len);
78
79/* Do a strcmp() type operation on STRING1 and STRING2, ignoring any
80 differences in whitespace. Returns 0 if they match, non-zero if
81 they don't (slightly different than strcmp()'s range of return
82 values).
83
84 As an extra hack, string1=="FOO(ARGS)" matches string2=="FOO".
85 This "feature" is useful when searching for matching C++ function
86 names (such as if the user types 'break FOO', where FOO is a
87 mangled C++ function).
88
89 Note: passes language_minimal to strncmp_iw_with_mode, and should
90 therefore be avoided if a more suitable language is available. */
91extern int strcmp_iw (const char *string1, const char *string2);
92
93extern int strcmp_iw_ordered (const char *, const char *);
94
95/* Reset the prompt_for_continue clock. */
97/* Return the time spent in prompt_for_continue. */
98std::chrono::steady_clock::duration get_prompt_for_continue_wait_time ();
99
100/* Parsing utilities. */
101
102extern int parse_pid_to_attach (const char *args);
103
104extern int parse_escape (struct gdbarch *, const char **);
105
106
107/* Cleanup utilities. */
108
109extern void init_page_info (void);
110
111/* Temporarily set BATCH_FLAG and the associated unlimited terminal size.
112 Restore when destroyed. */
113
115{
116public:
117
120
122
123private:
124
125 /* Note that this doesn't use scoped_restore, because it's important
126 to control the ordering of operations in the destruction, and it
127 was simpler to avoid introducing a new ad hoc class. */
131};
132
133
134/* Path utilities. */
135
136extern int gdb_filename_fnmatch (const char *pattern, const char *string,
137 int flags);
138
139extern void substitute_path_component (char **stringp, const char *from,
140 const char *to);
141
142std::string ldirname (const char *filename);
143
144extern int count_path_elements (const char *path);
145
146extern const char *strip_leading_path_elements (const char *path, int n);
147
148/* GDB output, ui_file utilities. */
149
150struct ui_file;
151
152extern int query (const char *, ...) ATTRIBUTE_PRINTF (1, 2);
153extern int nquery (const char *, ...) ATTRIBUTE_PRINTF (1, 2);
154extern int yquery (const char *, ...) ATTRIBUTE_PRINTF (1, 2);
155
156extern void begin_line (void);
157
158extern void wrap_here (int);
159
160extern void reinitialize_more_filter (void);
161
162/* Return the number of characters in a line. */
163
164extern int get_chars_per_line ();
165
166extern bool pagination_enabled;
167
168/* A flag indicating whether to timestamp debugging messages. */
169extern bool debug_timestamp;
170
171extern struct ui_file **current_ui_gdb_stdout_ptr (void);
172extern struct ui_file **current_ui_gdb_stdin_ptr (void);
173extern struct ui_file **current_ui_gdb_stderr_ptr (void);
174extern struct ui_file **current_ui_gdb_stdlog_ptr (void);
175
176/* Flush STREAM. */
177extern void gdb_flush (struct ui_file *stream);
178
179/* The current top level's ui_file streams. */
180
181/* Normal results */
182#define gdb_stdout (*current_ui_gdb_stdout_ptr ())
183/* Input stream */
184#define gdb_stdin (*current_ui_gdb_stdin_ptr ())
185/* Serious error notifications. This bypasses the pager, if one is in
186 use. */
187#define gdb_stderr (*current_ui_gdb_stderr_ptr ())
188/* Log/debug/trace messages that bypasses the pager, if one is in
189 use. */
190#define gdb_stdlog (*current_ui_gdb_stdlog_ptr ())
191
192/* Truly global ui_file streams. These are all defined in main.c. */
193
194/* Target output that should bypass the pager, if one is in use. */
195extern struct ui_file *gdb_stdtarg;
196extern struct ui_file *gdb_stdtargerr;
197extern struct ui_file *gdb_stdtargin;
198
199/* Set the screen dimensions to WIDTH and HEIGHT. */
200
201extern void set_screen_width_and_height (int width, int height);
202
203/* Generic stdio-like operations. */
204
205extern void gdb_puts (const char *, struct ui_file *);
206
207extern void gdb_putc (int c, struct ui_file *);
208
209extern void gdb_putc (int c);
210
211extern void gdb_puts (const char *);
212
213extern void puts_tabular (char *string, int width, int right);
214
215/* Generic printf-like operations. As an extension over plain
216 printf, these support some GDB-specific format specifiers.
217 Particularly useful here are the styling formatters: '%p[', '%p]'
218 and '%ps'. See ui_out::message for details. */
219
220extern void gdb_vprintf (const char *, va_list) ATTRIBUTE_PRINTF (1, 0);
221
222extern void gdb_vprintf (struct ui_file *, const char *, va_list)
223 ATTRIBUTE_PRINTF (2, 0);
224
225extern void gdb_printf (struct ui_file *, const char *, ...)
226 ATTRIBUTE_PRINTF (2, 3);
227
228extern void gdb_printf (const char *, ...) ATTRIBUTE_PRINTF (1, 2);
229
230extern void printf_unfiltered (const char *, ...) ATTRIBUTE_PRINTF (1, 2);
231
232extern void print_spaces (int, struct ui_file *);
233
234extern const char *n_spaces (int);
235
236/* Return nonzero if filtered printing is initialized. */
237extern int filtered_printing_initialized (void);
238
239/* Like gdb_printf, but styles the output according to STYLE,
240 when appropriate. */
241
242extern void fprintf_styled (struct ui_file *stream,
243 const ui_file_style &style,
244 const char *fmt,
245 ...)
246 ATTRIBUTE_PRINTF (3, 4);
247
248/* Like gdb_puts, but styles the output according to STYLE, when
249 appropriate. */
250
251extern void fputs_styled (const char *linebuffer,
252 const ui_file_style &style,
253 struct ui_file *stream);
254
255/* Like fputs_styled, but uses highlight_style to highlight the
256 parts of STR that match HIGHLIGHT. */
257
258extern void fputs_highlighted (const char *str, const compiled_regex &highlight,
259 struct ui_file *stream);
260
261/* Convert CORE_ADDR to string in platform-specific manner.
262 This is usually formatted similar to 0x%lx. */
263extern const char *paddress (struct gdbarch *gdbarch, CORE_ADDR addr);
264
265/* Return a string representation in hexadecimal notation of ADDRESS,
266 which is suitable for printing. */
267
268extern const char *print_core_address (struct gdbarch *gdbarch,
269 CORE_ADDR address);
270
271extern CORE_ADDR string_to_core_addr (const char *my_string);
272
273extern void fprintf_symbol (struct ui_file *, const char *,
274 enum language, int);
275
276extern void perror_warning_with_name (const char *string);
277
278/* Issue a warning formatted as '<filename>: <explanation>', where
279 <filename> is FILENAME with filename styling applied. As such, don't
280 pass anything more than a filename in this string. The <explanation>
281 is a string returned from calling safe_strerror(SAVED_ERRNO). */
282
283extern void warning_filename_and_errno (const char *filename,
284 int saved_errno);
285
286/* Warnings and error messages. */
287
288extern void (*deprecated_error_begin_hook) (void);
289
290/* Message to be printed before the warning message, when a warning occurs. */
291
292extern const char *warning_pre_print;
293
294extern void demangler_vwarning (const char *file, int line,
295 const char *, va_list ap)
296 ATTRIBUTE_PRINTF (3, 0);
297
298extern void demangler_warning (const char *file, int line,
299 const char *, ...) ATTRIBUTE_PRINTF (3, 4);
300
301
302/* Misc. utilities. */
303
304#ifdef HAVE_WAITPID
305extern pid_t wait_to_die_with_timeout (pid_t pid, int *status, int timeout);
306#endif
307
308extern int myread (int, char *, int);
309
310/* Resource limits used by getrlimit and setrlimit. */
311
317
318/* Check whether GDB will be able to dump core using the dump_core
319 function. Returns zero if GDB cannot or should not dump core.
320 If LIMIT_KIND is LIMIT_CUR the user's soft limit will be respected.
321 If LIMIT_KIND is LIMIT_MAX only the hard limit will be respected. */
322
323extern int can_dump_core (enum resource_limit_kind limit_kind);
324
325/* Print a warning that we cannot dump core. */
326
327extern void warn_cant_dump_core (const char *reason);
328
329/* Dump core trying to increase the core soft limit to hard limit
330 first. */
331
332extern void dump_core (void);
333
334/* Copy NBITS bits from SOURCE to DEST starting at the given bit
335 offsets. Use the bit order as specified by BITS_BIG_ENDIAN.
336 Source and destination buffers must not overlap. */
337
338extern void copy_bitwise (gdb_byte *dest, ULONGEST dest_offset,
339 const gdb_byte *source, ULONGEST source_offset,
340 ULONGEST nbits, int bits_big_endian);
341
342/* When readline decides that the terminal cannot auto-wrap lines, it reduces
343 the width of the reported screen width by 1. This variable indicates
344 whether that's the case or not, allowing us to add it back where
345 necessary. See _rl_term_autowrap in readline/terminal.c. */
346
347extern int readline_hidden_cols;
348
349/* Assign VAL to LVAL, and set CHANGED to true if the assignment changed
350 LVAL. */
351
352template<typename T>
353void
354assign_set_if_changed (T &lval, const T &val, bool &changed)
355{
356 if (lval == val)
357 return;
358
359 lval = val;
360 changed = true;
361}
362
363/* Assign VAL to LVAL, and return true if the assignment changed LVAL. */
364
365template<typename T>
366bool
367assign_return_if_changed (T &lval, const T &val)
368{
369 if (lval == val)
370 return false;
371
372 lval = val;
373 return true;
374}
375
376/* In some cases GDB needs to try several different solutions to a problem,
377 if any of the solutions work then as far as the user is concerned the
378 problem is solved, and GDB should continue without warnings. However,
379 if none of the solutions work then GDB should emit any warnings that
380 occurred while trying each possible solution.
381
382 One example of this is locating separate debug info. There are several
383 different approaches for this; following the .gnu_debuglink, a build-id
384 based lookup, or using debuginfod. If any works, and debug info is
385 located, then the user doesn't want to see warnings from the earlier
386 approaches that were tried and failed.
387
388 However, GDB should emit all the warnings using separate calls to
389 warning -- this ensures that each warning is formatted on its own line,
390 and that any styling is emitted correctly.
391
392 This class helps with deferring warnings. Warnings can be added to an
393 instance of this class with the 'warn' function, and all warnings can be
394 emitted with a single call to 'emit'. */
395
397{
398 /* Add a warning to the list of deferred warnings. */
399 void warn (const char *format, ...) ATTRIBUTE_PRINTF(2,3)
400 {
401 /* Generate the warning text into a string_file. We allow the text to
402 be styled only if gdb_stderr allows styling -- warnings are sent to
403 gdb_stderr. */
404 string_file msg (gdb_stderr->can_emit_style_escape ());
405
406 va_list args;
407 va_start (args, format);
408 msg.vprintf (format, args);
410
411 /* Move the text into the list of deferred warnings. */
412 m_warnings.emplace_back (std::move (msg));
413 }
414
415 /* Emit all warnings. */
416 void emit () const
417 {
418 for (const auto &w : m_warnings)
419 warning ("%s", w.c_str ());
420 }
421
422private:
423
424 /* The list of all deferred warnings. */
425 std::vector<string_file> m_warnings;
426};
427
428#endif /* UTILS_H */
void vprintf(const char *, va_list) ATTRIBUTE_PRINTF(2
Definition ui-file.c:71
language
Definition defs.h:211
static void ATTRIBUTE_PRINTF(1, 0)
Definition gdb_bfd.c:1154
mach_port_t kern_return_t mach_port_t mach_msg_type_name_t msgportsPoly mach_port_t kern_return_t pid_t pid mach_port_t kern_return_t mach_port_t task mach_port_t kern_return_t int flags
Definition gnu-nat.c:1861
mach_port_t mach_port_t name mach_port_t mach_port_t name kern_return_t int int rusage_t pid_t pid
Definition gnu-nat.c:1791
mach_port_t mach_port_t name mach_port_t mach_port_t name kern_return_t int status
Definition gnu-nat.c:1790
Definition 1.cc:26
void warn(const char *format,...) ATTRIBUTE_PRINTF(2
std::vector< string_file > m_warnings
Definition utils.h:425
void va_list args
Definition utils.h:406
va_start(args, format)
void emit() const
Definition utils.h:416
DISABLE_COPY_AND_ASSIGN(set_batch_flag_and_restore_page_info)
std::string ldirname(const char *filename)
Definition utils.c:3306
int parse_escape(struct gdbarch *, const char **)
Definition utils.c:996
void fprintf_styled(struct ui_file *stream, const ui_file_style &style, const char *fmt,...) ATTRIBUTE_PRINTF(3
struct ui_file ** current_ui_gdb_stdlog_ptr(void)
Definition top.c:118
int strncmp_iw(const char *string1, const char *string2, size_t string2_len)
Definition utils.c:3024
void set_screen_width_and_height(int width, int height)
Definition utils.c:1289
void demangler_vwarning(const char *file, int line, const char *, va_list ap) ATTRIBUTE_PRINTF(3
std::chrono::steady_clock::duration get_prompt_for_continue_wait_time()
Definition utils.c:1463
void init_page_info(void)
Definition utils.c:1124
bool debug_timestamp
Definition utils.c:102
void reinitialize_more_filter(void)
Definition utils.c:1471
const char * print_core_address(struct gdbarch *gdbarch, CORE_ADDR address)
Definition utils.c:3187
int can_dump_core(enum resource_limit_kind limit_kind)
Definition utils.c:207
strncmp_iw_mode
Definition utils.h:37
void assign_set_if_changed(T &lval, const T &val, bool &changed)
Definition utils.h:354
void void void void void void print_spaces(int, struct ui_file *)
Definition utils.c:1968
int int int void begin_line(void)
Definition utils.c:1589
const char * paddress(struct gdbarch *gdbarch, CORE_ADDR addr)
Definition utils.c:3166
void perror_warning_with_name(const char *string)
Definition utils.c:616
struct ui_file ** current_ui_gdb_stdin_ptr(void)
Definition top.c:106
void void void gdb_printf(struct ui_file *, const char *,...) ATTRIBUTE_PRINTF(2
int readline_hidden_cols
Definition utils.c:1119
int int nquery(const char *,...) ATTRIBUTE_PRINTF(1
#define gdb_stderr
Definition utils.h:187
void gdb_vprintf(const char *, va_list) ATTRIBUTE_PRINTF(1
bool sevenbit_strings
Definition utils.c:108
void fprintf_symbol(struct ui_file *, const char *, enum language, int)
Definition utils.c:1981
bool pagination_enabled
Definition utils.c:122
int query(const char *,...) ATTRIBUTE_PRINTF(1
int strncmp_iw_with_mode(const char *string1, const char *string2, size_t string2_len, strncmp_iw_mode mode, enum language language, completion_match_for_lcd *match_for_lcd=NULL, bool ignore_template_params=false)
Definition utils.c:2150
void fputs_highlighted(const char *str, const compiled_regex &highlight, struct ui_file *stream)
Definition utils.c:1828
int filtered_printing_initialized(void)
Definition utils.c:1194
void void demangler_warning(const char *file, int line, const char *,...) ATTRIBUTE_PRINTF(3
void reset_prompt_for_continue_wait_time(void)
Definition utils.c:1453
void copy_bitwise(gdb_byte *dest, ULONGEST dest_offset, const gdb_byte *source, ULONGEST source_offset, ULONGEST nbits, int bits_big_endian)
Definition utils.c:3588
struct ui_file * gdb_stdtarg
Definition main.c:80
int gdb_filename_fnmatch(const char *pattern, const char *string, int flags)
Definition utils.c:3472
struct ui_file * gdb_stdtargerr
Definition main.c:81
resource_limit_kind
Definition utils.h:313
@ LIMIT_MAX
Definition utils.h:315
@ LIMIT_CUR
Definition utils.h:314
void gdb_putc(int c, struct ui_file *)
Definition utils.c:1868
bool assign_return_if_changed(T &lval, const T &val)
Definition utils.h:367
void(* deprecated_error_begin_hook)(void)
Definition utils.c:85
void void int myread(int, char *, int)
Definition utils.c:702
int count_path_elements(const char *path)
Definition utils.c:3516
int int int yquery(const char *,...) ATTRIBUTE_PRINTF(1
struct ui_file * gdb_stdtargin
Definition main.c:79
int strcmp_iw_ordered(const char *, const char *)
Definition utils.c:3077
int get_chars_per_line()
Definition utils.c:1506
CORE_ADDR string_to_core_addr(const char *my_string)
Definition utils.c:3205
struct ui_file ** current_ui_gdb_stderr_ptr(void)
Definition top.c:112
void substitute_path_component(char **stringp, const char *from, const char *to)
Definition utils.c:3354
void void fputs_styled(const char *linebuffer, const ui_file_style &style, struct ui_file *stream)
Definition utils.c:1817
void wrap_here(int)
const char * strip_leading_path_elements(const char *path, int n)
Definition utils.c:3552
struct ui_file ** current_ui_gdb_stdout_ptr(void)
Definition top.c:100
void gdb_flush(struct ui_file *stream)
Definition utils.c:1498
void dump_core(void)
Definition utils.c:185
void gdb_puts(const char *, struct ui_file *)
Definition utils.c:1809
const char * warning_pre_print
Definition utils.c:120
void warn_cant_dump_core(const char *reason)
Definition utils.c:235
void puts_tabular(char *string, int width, int right)
Definition utils.c:1546
const char * n_spaces(int)
Definition utils.c:1947
void void void void void printf_unfiltered(const char *,...) ATTRIBUTE_PRINTF(1
void warning_filename_and_errno(const char *filename, int saved_errno)
Definition utils.c:625
int parse_pid_to_attach(const char *args)
Definition utils.c:3331
int strcmp_iw(const char *string1, const char *string2)
Definition utils.c:3033