1 /* Shared general utility routines for GDB, the GNU debugger. 2 3 Copyright (C) 1986-2024 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 "gdbsupport/array-view.h" 28 #include "poison.h" 29 #include <string_view> 30 31 #if defined HAVE_LIBXXHASH 32 # include <xxhash.h> 33 #else 34 # include "hashtab.h" 35 #endif 36 37 /* xmalloc(), xrealloc() and xcalloc() have already been declared in 38 "libiberty.h". */ 39 40 /* Like xmalloc, but zero the memory. */ 41 void *xzalloc (size_t); 42 43 /* Like asprintf and vasprintf, but return the string, throw an error 44 if no memory. */ 45 gdb::unique_xmalloc_ptr<char> xstrprintf (const char *format, ...) 46 ATTRIBUTE_PRINTF (1, 2); 47 gdb::unique_xmalloc_ptr<char> xstrvprintf (const char *format, va_list ap) 48 ATTRIBUTE_PRINTF (1, 0); 49 50 /* Like snprintf, but throw an error if the output buffer is too small. */ 51 int xsnprintf (char *str, size_t size, const char *format, ...) 52 ATTRIBUTE_PRINTF (3, 4); 53 54 /* Returns a std::string built from a printf-style format string. */ 55 std::string string_printf (const char* fmt, ...) 56 ATTRIBUTE_PRINTF (1, 2); 57 58 /* Like string_printf, but takes a va_list. */ 59 std::string string_vprintf (const char* fmt, va_list args) 60 ATTRIBUTE_PRINTF (1, 0); 61 62 /* Like string_printf, but appends to DEST instead of returning a new 63 std::string. */ 64 std::string &string_appendf (std::string &dest, const char* fmt, ...) 65 ATTRIBUTE_PRINTF (2, 3); 66 67 /* Like string_appendf, but takes a va_list. */ 68 std::string &string_vappendf (std::string &dest, const char* fmt, va_list args) 69 ATTRIBUTE_PRINTF (2, 0); 70 71 /* Make a copy of the string at PTR with LEN characters 72 (and add a null character at the end in the copy). 73 Uses malloc to get the space. Returns the address of the copy. */ 74 75 char *savestring (const char *ptr, size_t len); 76 77 /* Extract the next word from ARG. The next word is defined as either, 78 everything up to the next space, or, if the next word starts with either 79 a single or double quote, then everything up to the closing quote. The 80 enclosing quotes are not returned in the result string. The pointer in 81 ARG is updated to point to the first character after the end of the 82 word, or, for quoted words, the first character after the closing 83 quote. */ 84 85 std::string extract_string_maybe_quoted (const char **arg); 86 87 /* The strerror() function can return NULL for errno values that are 88 out of range. Provide a "safe" version that always returns a 89 printable string. This version is also thread-safe. */ 90 91 extern const char *safe_strerror (int); 92 93 /* Version of startswith that takes string_view arguments. Return 94 true if the start of STRING matches PATTERN, false otherwise. */ 95 96 static inline bool 97 startswith (std::string_view string, std::string_view pattern) 98 { 99 return (string.length () >= pattern.length () 100 && strncmp (string.data (), pattern.data (), pattern.length ()) == 0); 101 } 102 103 /* Return true if the strings are equal. */ 104 105 static inline bool 106 streq (const char *lhs, const char *rhs) 107 { 108 return strcmp (lhs, rhs) == 0; 109 } 110 111 /* Compare C strings for std::sort. */ 112 113 static inline bool 114 compare_cstrings (const char *str1, const char *str2) 115 { 116 return strcmp (str1, str2) < 0; 117 } 118 119 ULONGEST strtoulst (const char *num, const char **trailer, int base); 120 121 /* Skip leading whitespace characters in INP, returning an updated 122 pointer. If INP is NULL, return NULL. */ 123 124 extern char *skip_spaces (char *inp); 125 126 /* A const-correct version of the above. */ 127 128 extern const char *skip_spaces (const char *inp); 129 130 /* Skip leading non-whitespace characters in INP, returning an updated 131 pointer. If INP is NULL, return NULL. */ 132 133 extern char *skip_to_space (char *inp); 134 135 /* A const-correct version of the above. */ 136 137 extern const char *skip_to_space (const char *inp); 138 139 /* Assumes that V is an argv for a program, and iterates through 140 freeing all the elements. */ 141 extern void free_vector_argv (std::vector<char *> &v); 142 143 /* Return true if VALUE is in [LOW, HIGH]. */ 144 145 template <typename T> 146 static bool 147 in_inclusive_range (T value, T low, T high) 148 { 149 return value >= low && value <= high; 150 } 151 152 /* Ensure that V is aligned to an N byte boundary (N's assumed to be a 153 power of 2). Round up/down when necessary. Examples of correct 154 use include: 155 156 addr = align_up (addr, 8); -- VALUE needs 8 byte alignment 157 write_memory (addr, value, len); 158 addr += len; 159 160 and: 161 162 sp = align_down (sp - len, 16); -- Keep SP 16 byte aligned 163 write_memory (sp, value, len); 164 165 Note that uses such as: 166 167 write_memory (addr, value, len); 168 addr += align_up (len, 8); 169 170 and: 171 172 sp -= align_up (len, 8); 173 write_memory (sp, value, len); 174 175 are typically not correct as they don't ensure that the address (SP 176 or ADDR) is correctly aligned (relying on previous alignment to 177 keep things right). This is also why the methods are called 178 "align_..." instead of "round_..." as the latter reads better with 179 this incorrect coding style. */ 180 181 extern ULONGEST align_up (ULONGEST v, int n); 182 extern ULONGEST align_down (ULONGEST v, int n); 183 184 /* Convert hex digit A to a number, or throw an exception. */ 185 extern int fromhex (int a); 186 187 /* HEX is a string of characters representing hexadecimal digits. 188 Convert pairs of hex digits to bytes and store sequentially into 189 BIN. COUNT is the maximum number of characters to convert. This 190 will convert fewer characters if the number of hex characters 191 actually seen is odd, or if HEX terminates before COUNT characters. 192 Returns the number of characters actually converted. */ 193 extern int hex2bin (const char *hex, gdb_byte *bin, int count); 194 195 /* Like the above, but return a gdb::byte_vector. */ 196 gdb::byte_vector hex2bin (const char *hex); 197 198 /* Build a string containing the contents of BYTES. Each byte is 199 represented as a 2 character hex string, with spaces separating each 200 individual byte. */ 201 202 extern std::string bytes_to_string (gdb::array_view<const gdb_byte> bytes); 203 204 /* See bytes_to_string above. This takes a BUFFER pointer and LENGTH 205 rather than an array view. */ 206 207 static inline std::string bytes_to_string (const gdb_byte *buffer, 208 size_t length) 209 { 210 return bytes_to_string ({buffer, length}); 211 } 212 213 /* A fast hashing function. This can be used to hash data in a fast way 214 when the length is known. If no fast hashing library is available, falls 215 back to iterative_hash from libiberty. START_VALUE can be set to 216 continue hashing from a previous value. */ 217 218 static inline unsigned int 219 fast_hash (const void *ptr, size_t len, unsigned int start_value = 0) 220 { 221 #if defined HAVE_LIBXXHASH 222 return XXH64 (ptr, len, start_value); 223 #else 224 return iterative_hash (ptr, len, start_value); 225 #endif 226 } 227 228 namespace gdb 229 { 230 231 /* Hash type for std::string_view. 232 233 Even after we switch to C++17 and dump our string_view implementation, we 234 might want to keep this hash implementation if it's faster than std::hash 235 for std::string_view. */ 236 237 struct string_view_hash 238 { 239 std::size_t operator() (std::string_view view) const 240 { return fast_hash (view.data (), view.length ()); } 241 }; 242 243 } /* namespace gdb */ 244 245 #endif /* COMMON_COMMON_UTILS_H */ 246