gdbsupport/common-utils.h

   1 /* Shared general utility routines for GDB, the GNU debugger.
   2
   3    Copyright (C) 1986-2022 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
  27 #include "poison.h"
  28
  29 /* If possible, define FUNCTION_NAME, a macro containing the name of
  30    the function being defined.  Since this macro may not always be
  31    defined, all uses must be protected by appropriate macro definition
  32    checks (Eg: "#ifdef FUNCTION_NAME").
  33
  34    Version 2.4 and later of GCC define a magical variable `__PRETTY_FUNCTION__'
  35    which contains the name of the function currently being defined.
  36    This is broken in G++ before version 2.6.
  37    C9x has a similar variable called __func__, but prefer the GCC one since
  38    it demangles C++ function names.  */
  39 #if (GCC_VERSION >= 2004)
  40 #define FUNCTION_NAME           __PRETTY_FUNCTION__
  41 #else
  42 #if defined __STDC_VERSION__ && __STDC_VERSION__ >= 199901L
  43 #define FUNCTION_NAME           __func__  /* ARI: func */
  44 #endif
  45 #endif
  46
  47 #include "gdb_string_view.h"
  48
  49 /* xmalloc(), xrealloc() and xcalloc() have already been declared in
  50    "libiberty.h". */
  51
  52 /* Like xmalloc, but zero the memory.  */
  53 void *xzalloc (size_t);
  54
  55 template <typename T>
  56 static void
  57 xfree (T *ptr)
  58 {
  59   static_assert (IsFreeable<T>::value, "Trying to use xfree with a non-POD \
  60 data type.  Use operator delete instead.");
  61
  62   if (ptr != NULL)
  63 #ifdef GNULIB_NAMESPACE
  64     GNULIB_NAMESPACE::free (ptr);       /* ARI: free */
  65 #else
  66     free (ptr);                         /* ARI: free */
  67 #endif
  68 }
  69
  70
  71 /* Like asprintf and vasprintf, but return the string, throw an error
  72    if no memory.  */
  73 char *xstrprintf (const char *format, ...) ATTRIBUTE_PRINTF (1, 2);
  74 char *xstrvprintf (const char *format, va_list ap)
  75      ATTRIBUTE_PRINTF (1, 0);
  76
  77 /* Like snprintf, but throw an error if the output buffer is too small.  */
  78 int xsnprintf (char *str, size_t size, const char *format, ...)
  79      ATTRIBUTE_PRINTF (3, 4);
  80
  81 /* Returns a std::string built from a printf-style format string.  */
  82 std::string string_printf (const char* fmt, ...)
  83   ATTRIBUTE_PRINTF (1, 2);
  84
  85 /* Like string_printf, but takes a va_list.  */
  86 std::string string_vprintf (const char* fmt, va_list args)
  87   ATTRIBUTE_PRINTF (1, 0);
  88
  89 /* Like string_printf, but appends to DEST instead of returning a new
  90    std::string.  */
  91 void string_appendf (std::string &dest, const char* fmt, ...)
  92   ATTRIBUTE_PRINTF (2, 3);
  93
  94 /* Like string_appendf, but takes a va_list.  */
  95 void string_vappendf (std::string &dest, const char* fmt, va_list args)
  96   ATTRIBUTE_PRINTF (2, 0);
  97
  98 /* Make a copy of the string at PTR with LEN characters
  99    (and add a null character at the end in the copy).
 100    Uses malloc to get the space.  Returns the address of the copy.  */
 101
 102 char *savestring (const char *ptr, size_t len);
 103
 104 /* Extract the next word from ARG.  The next word is defined as either,
 105    everything up to the next space, or, if the next word starts with either
 106    a single or double quote, then everything up to the closing quote.  The
 107    enclosing quotes are not returned in the result string.  The pointer in
 108    ARG is updated to point to the first character after the end of the
 109    word, or, for quoted words, the first character after the closing
 110    quote.  */
 111
 112 std::string extract_string_maybe_quoted (const char **arg);
 113
 114 /* The strerror() function can return NULL for errno values that are
 115    out of range.  Provide a "safe" version that always returns a
 116    printable string.  This version is also thread-safe.  */
 117
 118 extern const char *safe_strerror (int);
 119
 120 /* Version of startswith that takes string_view arguments.  Return
 121    true if the start of STRING matches PATTERN, false otherwise.  */
 122
 123 static inline bool
 124 startswith (gdb::string_view string, gdb::string_view pattern)
 125 {
 126   return (string.length () >= pattern.length ()
 127           && strncmp (string.data (), pattern.data (), pattern.length ()) == 0);
 128 }
 129
 130 ULONGEST strtoulst (const char *num, const char **trailer, int base);
 131
 132 /* Skip leading whitespace characters in INP, returning an updated
 133    pointer.  If INP is NULL, return NULL.  */
 134
 135 extern char *skip_spaces (char *inp);
 136
 137 /* A const-correct version of the above.  */
 138
 139 extern const char *skip_spaces (const char *inp);
 140
 141 /* Skip leading non-whitespace characters in INP, returning an updated
 142    pointer.  If INP is NULL, return NULL.  */
 143
 144 extern char *skip_to_space (char *inp);
 145
 146 /* A const-correct version of the above.  */
 147
 148 extern const char *skip_to_space (const char *inp);
 149
 150 /* Assumes that V is an argv for a program, and iterates through
 151    freeing all the elements.  */
 152 extern void free_vector_argv (std::vector<char *> &v);
 153
 154 /* Return true if VALUE is in [LOW, HIGH].  */
 155
 156 template <typename T>
 157 static bool
 158 in_inclusive_range (T value, T low, T high)
 159 {
 160   return value >= low && value <= high;
 161 }
 162
 163 /* Ensure that V is aligned to an N byte boundary (N's assumed to be a
 164    power of 2).  Round up/down when necessary.  Examples of correct
 165    use include:
 166
 167     addr = align_up (addr, 8); -- VALUE needs 8 byte alignment
 168     write_memory (addr, value, len);
 169     addr += len;
 170
 171    and:
 172
 173     sp = align_down (sp - len, 16); -- Keep SP 16 byte aligned
 174     write_memory (sp, value, len);
 175
 176    Note that uses such as:
 177
 178     write_memory (addr, value, len);
 179     addr += align_up (len, 8);
 180
 181    and:
 182
 183     sp -= align_up (len, 8);
 184     write_memory (sp, value, len);
 185
 186    are typically not correct as they don't ensure that the address (SP
 187    or ADDR) is correctly aligned (relying on previous alignment to
 188    keep things right).  This is also why the methods are called
 189    "align_..." instead of "round_..." as the latter reads better with
 190    this incorrect coding style.  */
 191
 192 extern ULONGEST align_up (ULONGEST v, int n);
 193 extern ULONGEST align_down (ULONGEST v, int n);
 194
 195 /* Convert hex digit A to a number, or throw an exception.  */
 196 extern int fromhex (int a);
 197
 198 /* HEX is a string of characters representing hexadecimal digits.
 199    Convert pairs of hex digits to bytes and store sequentially into
 200    BIN.  COUNT is the maximum number of characters to convert.  This
 201    will convert fewer characters if the number of hex characters
 202    actually seen is odd, or if HEX terminates before COUNT characters.
 203    Returns the number of characters actually converted.  */
 204 extern int hex2bin (const char *hex, gdb_byte *bin, int count);
 205
 206 /* Like the above, but return a gdb::byte_vector.  */
 207 gdb::byte_vector hex2bin (const char *hex);
 208
 209 #endif /* COMMON_COMMON_UTILS_H */