gdbsupport/common-utils.h

   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 GDBSUPPORT_COMMON_UTILS_H
  21 #define GDBSUPPORT_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 /* Return a copy of STR, but with any white space, single quote, or
  88    double quote characters escaped with a backslash.  */
  89
  90 std::string make_quoted_string (const char *str);
  91
  92 /* The strerror() function can return NULL for errno values that are
  93    out of range.  Provide a "safe" version that always returns a
  94    printable string.  This version is also thread-safe.  */
  95
  96 extern const char *safe_strerror (int);
  97
  98 /* Version of startswith that takes string_view arguments.  Return
  99    true if the start of STRING matches PATTERN, false otherwise.  */
 100
 101 static inline bool
 102 startswith (std::string_view string, std::string_view pattern)
 103 {
 104   return (string.length () >= pattern.length ()
 105           && strncmp (string.data (), pattern.data (), pattern.length ()) == 0);
 106 }
 107
 108 /* Version of startswith that takes a string_view for only one of its
 109    arguments.  Return true if STR starts with PREFIX, otherwise return
 110    false.  */
 111
 112 static inline bool
 113 startswith (const char *str, const std::string_view &prefix)
 114 {
 115   return strncmp (str, prefix.data (), prefix.length ()) == 0;
 116 }
 117
 118 /* Return true if the strings are equal.  */
 119
 120 static inline bool
 121 streq (const char *lhs, const char *rhs)
 122 {
 123   return strcmp (lhs, rhs) == 0;
 124 }
 125
 126 /* Compare C strings for std::sort.  */
 127
 128 static inline bool
 129 compare_cstrings (const char *str1, const char *str2)
 130 {
 131   return strcmp (str1, str2) < 0;
 132 }
 133
 134 ULONGEST strtoulst (const char *num, const char **trailer, int base);
 135
 136 /* Skip leading whitespace characters in INP, returning an updated
 137    pointer.  If INP is NULL, return NULL.  */
 138
 139 extern char *skip_spaces (char *inp);
 140
 141 /* A const-correct version of the above.  */
 142
 143 extern const char *skip_spaces (const char *inp);
 144
 145 /* Skip leading non-whitespace characters in INP, returning an updated
 146    pointer.  If INP is NULL, return NULL.  */
 147
 148 extern char *skip_to_space (char *inp);
 149
 150 /* A const-correct version of the above.  */
 151
 152 extern const char *skip_to_space (const char *inp);
 153
 154 /* Assumes that V is an argv for a program, and iterates through
 155    freeing all the elements.  */
 156 extern void free_vector_argv (std::vector<char *> &v);
 157
 158 /* Return true if VALUE is in [LOW, HIGH].  */
 159
 160 template <typename T>
 161 static bool
 162 in_inclusive_range (T value, T low, T high)
 163 {
 164   return value >= low && value <= high;
 165 }
 166
 167 /* Ensure that V is aligned to an N byte boundary (N's assumed to be a
 168    power of 2).  Round up/down when necessary.  Examples of correct
 169    use include:
 170
 171     addr = align_up (addr, 8); -- VALUE needs 8 byte alignment
 172     write_memory (addr, value, len);
 173     addr += len;
 174
 175    and:
 176
 177     sp = align_down (sp - len, 16); -- Keep SP 16 byte aligned
 178     write_memory (sp, value, len);
 179
 180    Note that uses such as:
 181
 182     write_memory (addr, value, len);
 183     addr += align_up (len, 8);
 184
 185    and:
 186
 187     sp -= align_up (len, 8);
 188     write_memory (sp, value, len);
 189
 190    are typically not correct as they don't ensure that the address (SP
 191    or ADDR) is correctly aligned (relying on previous alignment to
 192    keep things right).  This is also why the methods are called
 193    "align_..." instead of "round_..." as the latter reads better with
 194    this incorrect coding style.  */
 195
 196 extern ULONGEST align_up (ULONGEST v, int n);
 197 extern ULONGEST align_down (ULONGEST v, int n);
 198
 199 /* Convert hex digit A to a number, or throw an exception.  */
 200 extern int fromhex (int a);
 201
 202 /* HEX is a string of characters representing hexadecimal digits.
 203    Convert pairs of hex digits to bytes and store sequentially into
 204    BIN.  COUNT is the maximum number of characters to convert.  This
 205    will convert fewer characters if the number of hex characters
 206    actually seen is odd, or if HEX terminates before COUNT characters.
 207    Returns the number of characters actually converted.  */
 208 extern int hex2bin (const char *hex, gdb_byte *bin, int count);
 209
 210 /* Like the above, but return a gdb::byte_vector.  */
 211 gdb::byte_vector hex2bin (const char *hex);
 212
 213 /* Build a string containing the contents of BYTES.  Each byte is
 214    represented as a 2 character hex string, with spaces separating each
 215    individual byte.  */
 216
 217 extern std::string bytes_to_string (gdb::array_view<const gdb_byte> bytes);
 218
 219 /* See bytes_to_string above.  This takes a BUFFER pointer and LENGTH
 220    rather than an array view.  */
 221
 222 static inline std::string bytes_to_string (const gdb_byte *buffer,
 223                                            size_t length)
 224 {
 225   return bytes_to_string ({buffer, length});
 226 }
 227
 228 /* A fast hashing function.  This can be used to hash data in a fast way
 229    when the length is known.  If no fast hashing library is available, falls
 230    back to iterative_hash from libiberty.  START_VALUE can be set to
 231    continue hashing from a previous value.  */
 232
 233 static inline unsigned int
 234 fast_hash (const void *ptr, size_t len, unsigned int start_value = 0)
 235 {
 236 #if defined HAVE_LIBXXHASH
 237   return XXH64 (ptr, len, start_value);
 238 #else
 239   return iterative_hash (ptr, len, start_value);
 240 #endif
 241 }
 242
 243 namespace gdb
 244 {
 245
 246 /* Hash type for std::string_view.
 247
 248    Even after we switch to C++17 and dump our string_view implementation, we
 249    might want to keep this hash implementation if it's faster than std::hash
 250    for std::string_view.  */
 251
 252 struct string_view_hash
 253 {
 254   std::size_t operator() (std::string_view view) const
 255   {  return fast_hash (view.data (), view.length ()); }
 256 };
 257
 258 } /* namespace gdb */
 259
 260 #endif /* GDBSUPPORT_COMMON_UTILS_H */