1 /* Shared general utility routines for GDB, the GNU debugger. 2 3 Copyright (C) 1986-2023 Free Software Foundation, Inc. 4 5 This file is part of GDB. 6 7 This program is free software; you can redistribute it and/or modify 8 it under the terms of the GNU General Public License as published by 9 the Free Software Foundation; either version 3 of the License, or 10 (at your option) any later version. 11 12 This program is distributed in the hope that it will be useful, 13 but WITHOUT ANY WARRANTY; without even the implied warranty of 14 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 15 GNU General Public License for more details. 16 17 You should have received a copy of the GNU General Public License 18 along with this program. If not, see <http://www.gnu.org/licenses/>. */ 19 20 #ifndef COMMON_COMMON_UTILS_H 21 #define COMMON_COMMON_UTILS_H 22 23 #include <string> 24 #include <vector> 25 #include "gdbsupport/byte-vector.h" 26 #include "gdbsupport/gdb_unique_ptr.h" 27 #include "poison.h" 28 #include "gdb_string_view.h" 29 30 /* xmalloc(), xrealloc() and xcalloc() have already been declared in 31 "libiberty.h". */ 32 33 /* Like xmalloc, but zero the memory. */ 34 void *xzalloc (size_t); 35 36 /* Like asprintf and vasprintf, but return the string, throw an error 37 if no memory. */ 38 gdb::unique_xmalloc_ptr<char> xstrprintf (const char *format, ...) 39 ATTRIBUTE_PRINTF (1, 2); 40 gdb::unique_xmalloc_ptr<char> xstrvprintf (const char *format, va_list ap) 41 ATTRIBUTE_PRINTF (1, 0); 42 43 /* Like snprintf, but throw an error if the output buffer is too small. */ 44 int xsnprintf (char *str, size_t size, const char *format, ...) 45 ATTRIBUTE_PRINTF (3, 4); 46 47 /* Returns a std::string built from a printf-style format string. */ 48 std::string string_printf (const char* fmt, ...) 49 ATTRIBUTE_PRINTF (1, 2); 50 51 /* Like string_printf, but takes a va_list. */ 52 std::string string_vprintf (const char* fmt, va_list args) 53 ATTRIBUTE_PRINTF (1, 0); 54 55 /* Like string_printf, but appends to DEST instead of returning a new 56 std::string. */ 57 std::string &string_appendf (std::string &dest, const char* fmt, ...) 58 ATTRIBUTE_PRINTF (2, 3); 59 60 /* Like string_appendf, but takes a va_list. */ 61 std::string &string_vappendf (std::string &dest, const char* fmt, va_list args) 62 ATTRIBUTE_PRINTF (2, 0); 63 64 /* Make a copy of the string at PTR with LEN characters 65 (and add a null character at the end in the copy). 66 Uses malloc to get the space. Returns the address of the copy. */ 67 68 char *savestring (const char *ptr, size_t len); 69 70 /* Extract the next word from ARG. The next word is defined as either, 71 everything up to the next space, or, if the next word starts with either 72 a single or double quote, then everything up to the closing quote. The 73 enclosing quotes are not returned in the result string. The pointer in 74 ARG is updated to point to the first character after the end of the 75 word, or, for quoted words, the first character after the closing 76 quote. */ 77 78 std::string extract_string_maybe_quoted (const char **arg); 79 80 /* The strerror() function can return NULL for errno values that are 81 out of range. Provide a "safe" version that always returns a 82 printable string. This version is also thread-safe. */ 83 84 extern const char *safe_strerror (int); 85 86 /* Version of startswith that takes string_view arguments. Return 87 true if the start of STRING matches PATTERN, false otherwise. */ 88 89 static inline bool 90 startswith (gdb::string_view string, gdb::string_view pattern) 91 { 92 return (string.length () >= pattern.length () 93 && strncmp (string.data (), pattern.data (), pattern.length ()) == 0); 94 } 95 96 /* Return true if the strings are equal. */ 97 98 static inline bool 99 streq (const char *lhs, const char *rhs) 100 { 101 return strcmp (lhs, rhs) == 0; 102 } 103 104 /* Compare C strings for std::sort. */ 105 106 static inline bool 107 compare_cstrings (const char *str1, const char *str2) 108 { 109 return strcmp (str1, str2) < 0; 110 } 111 112 ULONGEST strtoulst (const char *num, const char **trailer, int base); 113 114 /* Skip leading whitespace characters in INP, returning an updated 115 pointer. If INP is NULL, return NULL. */ 116 117 extern char *skip_spaces (char *inp); 118 119 /* A const-correct version of the above. */ 120 121 extern const char *skip_spaces (const char *inp); 122 123 /* Skip leading non-whitespace characters in INP, returning an updated 124 pointer. If INP is NULL, return NULL. */ 125 126 extern char *skip_to_space (char *inp); 127 128 /* A const-correct version of the above. */ 129 130 extern const char *skip_to_space (const char *inp); 131 132 /* Assumes that V is an argv for a program, and iterates through 133 freeing all the elements. */ 134 extern void free_vector_argv (std::vector<char *> &v); 135 136 /* Return true if VALUE is in [LOW, HIGH]. */ 137 138 template <typename T> 139 static bool 140 in_inclusive_range (T value, T low, T high) 141 { 142 return value >= low && value <= high; 143 } 144 145 /* Ensure that V is aligned to an N byte boundary (N's assumed to be a 146 power of 2). Round up/down when necessary. Examples of correct 147 use include: 148 149 addr = align_up (addr, 8); -- VALUE needs 8 byte alignment 150 write_memory (addr, value, len); 151 addr += len; 152 153 and: 154 155 sp = align_down (sp - len, 16); -- Keep SP 16 byte aligned 156 write_memory (sp, value, len); 157 158 Note that uses such as: 159 160 write_memory (addr, value, len); 161 addr += align_up (len, 8); 162 163 and: 164 165 sp -= align_up (len, 8); 166 write_memory (sp, value, len); 167 168 are typically not correct as they don't ensure that the address (SP 169 or ADDR) is correctly aligned (relying on previous alignment to 170 keep things right). This is also why the methods are called 171 "align_..." instead of "round_..." as the latter reads better with 172 this incorrect coding style. */ 173 174 extern ULONGEST align_up (ULONGEST v, int n); 175 extern ULONGEST align_down (ULONGEST v, int n); 176 177 /* Convert hex digit A to a number, or throw an exception. */ 178 extern int fromhex (int a); 179 180 /* HEX is a string of characters representing hexadecimal digits. 181 Convert pairs of hex digits to bytes and store sequentially into 182 BIN. COUNT is the maximum number of characters to convert. This 183 will convert fewer characters if the number of hex characters 184 actually seen is odd, or if HEX terminates before COUNT characters. 185 Returns the number of characters actually converted. */ 186 extern int hex2bin (const char *hex, gdb_byte *bin, int count); 187 188 /* Like the above, but return a gdb::byte_vector. */ 189 gdb::byte_vector hex2bin (const char *hex); 190 191 #endif /* COMMON_COMMON_UTILS_H */ 192