gdbsupport/common-utils.h

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